From 08f856b490af73d80fb2b5a92030d4fa2b9273a8 Mon Sep 17 00:00:00 2001 From: Mountain Man Date: Tue, 4 Apr 2023 02:47:09 -0400 Subject: Write the initial `README.md` Every good project needs a `README.md` file. This document summarizes MMOSMacs, outlines my plans for the project, and directs contributors to the `CONTRIBUTING.md` file (which hasn't been written yet, that's next on my TODO list). --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 89256f1..4a9bfdb 100644 --- a/README.md +++ b/README.md @@ -1 +1,42 @@ -# MMOSMacs \ No newline at end of file +# MMOSMacs + +MMOSMacs is the Emacs configuration for MMOS, which is currently just an +idea I have for an Emacs-centric Linux distribution. MMOSMacs is the +core of my computing experience, and is designed to be a +jack-of-all-trades just like me. + +MMOSMacs is currently in the planning phase. + + +## Plans + +- Modular non-literate configuration +- `straight.el` + `use-package` package management +- Emacs as a desktop environment (`EXWM`, `EDNC`) +- System & network administration suite +- Security & crytography +- Software development environment +- Communications (Email, RSS, IRC, Matrix, etc.) +- Opinionated PKMS and publishing suite +- Common desktop applications + - Web browser, FTP, Torrent + - Multimedia production + - OpenSCAD / ImplicitCAD + - Finance + - Games +- Custom modeline & anti-distraction features +- Custom theme deisnged to reduce eye-strain +- Custom keybinds, menus, & dialogs + +## Contributing + +This is my personal project. I will do what I can to make it accessible +to other people, but ultimately it is crafted to suit my own needs. + +If you want to contribute to MMOSMacs, please read `CONTRIBUTING.md`. If +you do not have a copy of this file, it can be found at either: +- https://github.com/MountainMan1312/MMOSMacs/blob/stable/README.md +- https://raw.githubusercontent.com/MountainMan1312/MMOSMacs/stable/README.md + +Feel free to fork this repository. There is no need to give me credit. +It is wrong to claim ownership of knowledge. -- cgit v1.2.3 From ec023df146280cb4315f23cd4940094eb638d61b Mon Sep 17 00:00:00 2001 From: Mountain Man Date: Sat, 8 Apr 2023 15:38:36 -0400 Subject: Create `CONTRIBUTING.md` `CONTRIBUTING.md` is a standard file to have in any open-source repository. This file instructs new contributors on how to contribute to the project, as well as the Code of Conduct. --- CONTRIBUTING.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..d450c7d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,57 @@ +# Contributing to MMOSMacs + +Howdy, and welcome to the MMOSMacs git repository. This document +outlines the conventions and standards for the project. + + +## This is personal + +Please understand that this is my personal Emacs configuration. MMOSMacs +is designed to meet my personal needs. I welcome any and all +contributions, and I will do my best to make MMOSMacs accessible to +others, but my needs and preferences ultimately take priority. + +All contributors are listed at the end of this document. If you have +contributed and your name does not appear here, submit a PR or RFC Issue +for it to be added. + + +## Code of Conduct + +I will reject all contributions from: +- people who abuse other contributors. +- people I know to be affiliated with any state agency. + +Furthermore, individual items will be rejected because of: +- exceptionally vulgar language. +- ignorance or disregard of the `STYLE_GUIDE.md` or Issue/PR templates. + + +## How to Contribute + +There are several ways you can contribute. + +The easiest way you can contribute is by taking part in the discussions +on the [GitHub Issues page](https://github.com/MountainMan1312/MMOSMacs/Issues). +You can comment on topics that already have an existing Issue, or you +can submit your own if it does not already exist. Issues can take the +form of: +- **Feedback**: share your thoughts about MMOSMacs. +- **Bug Report**: discusion about a problem with the MMOSMacs code. +- **RFC**: discussion about making a change to MMOSMacs. + +Before submitting a new issue, search for existing duplicate issues. If +it already exists, comment on the existing Issue instead of making a new +one. Duplicate issues will be removed and you will be asked to move your +post to the comment section of the existing post. It's not to be rude, +it's just for organization's sake. + +Each type of Issue has an Issue Template. The templates can be found in +the `.github/ISSUE_TEMPLATE/` directory. Pull reqeusts also have +templates which are located in `.github/PULL_REQUEST_TEMPLATE/`. + +To contribute code: +1. Make an RFC or find an existing one +2. Discuss your proposed changes +3. Make your changes +4. Submit a Pull Request -- cgit v1.2.3 From 98ed8e7dedaf6a5d6844a18d1f9e72dfaf174701 Mon Sep 17 00:00:00 2001 From: Mountain Man Date: Sat, 8 Apr 2023 15:45:27 -0400 Subject: Create `STYLE_GUIDE.md` A style guide is necessary to keep the contents of the repository consistent. I've created an initial set of guidelines, based loosely on the guide fount at https://github.com/bbatsov/emacs-lisp-style-guide. --- STYLE_GUIDE.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 STYLE_GUIDE.md diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md new file mode 100644 index 0000000..d1e4e6b --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,149 @@ +# STYLE_GUIDE for MMOSMacs + +Much of this Style Guide was taken from +[bbatsov/emacs-lisp-style-guide](https://github.com/bbatsov/emacs-lisp-style-guide). + + +# General guidelines + +- Use spaces for indentation. Do not use tabs anywhere. +- Where feasible, avoid making lines longer than 72 chars. +- Avoid trailing whitespace. + + +## Organization + +Emacs Lisp files should begin with a header. The first line of the +header should include the filename, a very brief comment (2-5 words), +and the `-*- lexical-binding: t; -*-` thing. The next line(s) should be +a more detailed description of the file and it's purpose. + +```elisp +;;; -*- lexical-binding: t; -*- +;;; init.el +;; +;; Main config file for MMOSMacs; the glue that binds the modules +;; together. Provides package management, performance tweaks, and +;; integrates all the other MMOSMacs modules. +``` + +All Emacs Lisp files are organized into Sections and Subsections using +comment decorations. Section titles begin with `;;;`, are ALL CAPS, and +their decorations extend up to 72 chars. Subsections begin with `;;` +and their decorations extend up to 36 chars. Titles should be underlined +with dashes on the proceeding line. Explanatory comments go below the +title underline, and an additional 36-or-72-char line goes at the bottom +of the header. + +Each subsection should have 2 blank lines between the top line of the +header and the bottom line of code from the previous subsection. Only +one line goes between the Section header and the first Subsection, as +well as between portions of code within the same subsection. 4 lines go +between a new Section header and the previous bit of code. + +```elisp +;; integrates all the other MMOSMacs modules. + + +;; --------------------------------------------------------------------- +;;; FIRST SECTION TITLE +;; -------------------- +;; Comments about the purpose of the section go here. +;; It should be concise. Don't go into too much detail. +;; --------------------------------------------------------------------- + +;; --------------------------------- +;; Subsection Title +;; ---------------- +;; Subsection explanatory text goes +;; here. Limit the line length to 36 +;; chars to maintain the visual +;; "togetherness" of the header. +;; +;; Notice only 1 space between the +;; Section header and the top of the +;; first Subsection header. +;; --------------------------------- + +;; `something` is a package I bet +(use-package something + :straight t + :init + (setq some-crap nil)) + +;; `something-else` is a little less +;; likely to be a package +(use-package something-else + :straight t) + + +;; --------------------------------- +;; Subsection Title +;; ---------------- +;; Notice the 2 lines separating +;; each Subsection. +;; --------------------------------- + +;; I really don't know what to write +;; in these example comments. +(use-package some-other-thing + :straight + :init + (other-thing-mode)) + + + + +;; --------------------------------------------------------------------- +;;; SECOND SECTION TITLE +;; --------------------- +;; Notice the 4 empty lines above this section. +;; This provides visual separation; easier on the eyes. +;; --------------------------------------------------------------------- +``` + + +## Comments & Annotations + +- Write heading comments with 3 semicolons, and regular comments with 2. +- Write margin comments with 1 semicolon. +- Leave 1 space between the semicolons and the comment text. +- Comments longer than 1 word are capitalized and use punctuation. + +```elisp +;;; This is a heading comment +;; This is a regular comment with more words and stuff. +;; Something something something. +(defun foo (bar) + (something something + something-else)) ; for some other reason +``` + + +## Docstrings + +- Begin docstrings with a terse, complete sentence. Use imperative +language (e.g. "Verify" instead of "Verifies") +- When a function takes arguments, mention what the arguments do, +whether they are optional or required, etc. Describe the arguments in +UPPERCASE, and describe them in the order they are used in the function. +- Do not indent subsequent lines of a docstring. It looks nice in source +code but looks bizarre when viewed in Emacs. + +```elisp +;; good +(defun goto-line (line &optional buffer) + "Go to LINE, counting from line 1 at beginning of buffer. +If called interactively, a numeric prefix argument specifies +LINE; without a numeric prefix argument, read LINE from the +minibuffer..." +...) + +;; bad +(defun goto-line (line &optional buffer) + "Go to LINE, counting from line 1 at beginning of buffer. + If called interactively, a numeric prefix argument specifies + LINE; without a numeric prefix argument, read LINE from the + minibuffer..." +...) +``` -- cgit v1.2.3