Merge `initial-plans-docs` branch to `stable` branch

3 files changed, 248 insertions, 1 deletions

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
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.
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..."
+...)
+```