diff options
| author | Mountain Man <43313373+MountainMan1312@users.noreply.github.com> | 2023-04-14 17:32:41 -0400 |
|---|---|---|
| committer | Mountain Man <43313373+MountainMan1312@users.noreply.github.com> | 2023-04-14 17:32:41 -0400 |
| commit | af0e53a515dfa0c29094d0109ac5f9c2302bd0e9 (patch) | |
| tree | c869a30527b3e6e4e6c4cbdd185eef057d1ae34e | |
| parent | Fix phrasing in the documentation (diff) | |
| download | mmosmacs-af0e53a515dfa0c29094d0109ac5f9c2302bd0e9.tar.gz mmosmacs-af0e53a515dfa0c29094d0109ac5f9c2302bd0e9.tar.bz2 mmosmacs-af0e53a515dfa0c29094d0109ac5f9c2302bd0e9.zip | |
Modify `CONTRIBUTING.md` to be more informative and instructive
| -rw-r--r-- | CONTRIBUTING.md | 88 |
1 files changed, 83 insertions, 5 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42ae6d8..2594ed3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md | |||
| @@ -24,7 +24,7 @@ I will reject all contributions from: | |||
| 24 | 24 | ||
| 25 | Furthermore, individual items will be rejected because of: | 25 | Furthermore, individual items will be rejected because of: |
| 26 | - exceptionally vulgar language. | 26 | - exceptionally vulgar language. |
| 27 | - ignorance or disregard of the `STYLE_GUIDE.md` | 27 | - ignorance or disregard of the `STYLE_GUIDE.md` or Issue templates. |
| 28 | 28 | ||
| 29 | 29 | ||
| 30 | ## How to Contribute | 30 | ## How to Contribute |
| @@ -36,9 +36,9 @@ on the [GitHub Issues page](https://github.com/MountainMan1312/MMOSMacs/Issues). | |||
| 36 | You can comment on topics that already have an existing Issue, or you | 36 | You can comment on topics that already have an existing Issue, or you |
| 37 | can submit your own if it does not already exist. Issues can take the | 37 | can submit your own if it does not already exist. Issues can take the |
| 38 | form of: | 38 | form of: |
| 39 | - **Feedback**: share your thoughts about MMOSMacs. | ||
| 40 | - **Bug Report**: discusion about a problem with the MMOSMacs code. | ||
| 41 | - **RFC**: discussion about making a change to MMOSMacs. | 39 | - **RFC**: discussion about making a change to MMOSMacs. |
| 40 | - **Bug Report**: discusion about a problem with the MMOSMacs code. | ||
| 41 | - **Feedback**: share your thoughts about MMOSMacs. | ||
| 42 | 42 | ||
| 43 | Before submitting a new issue, search for existing duplicate issues. If | 43 | Before submitting a new issue, search for existing duplicate issues. If |
| 44 | it already exists, comment on the existing Issue instead of making a new | 44 | it already exists, comment on the existing Issue instead of making a new |
| @@ -49,5 +49,83 @@ it's just for organization's sake. | |||
| 49 | To contribute code: | 49 | To contribute code: |
| 50 | 1. Make an RFC or find an existing one | 50 | 1. Make an RFC or find an existing one |
| 51 | 2. Discuss your proposed changes | 51 | 2. Discuss your proposed changes |
| 52 | 3. Make your changes | 52 | 3. Create a branch |
| 53 | 4. Submit a Pull Request | 53 | 4. Make your changes |
| 54 | 5. Submit a Pull Request | ||
| 55 | |||
| 56 | |||
| 57 | ### RFC Issues, branches, commits, & Pull Requests | ||
| 58 | |||
| 59 | #### Writing an RFC | ||
| 60 | |||
| 61 | RFCs are the main form of project management for this repository. All | ||
| 62 | major changes to MMOSMacs should have an associated RFC. RFC Issues | ||
| 63 | should be named in the format `RFC: TITLE`, where title is a short | ||
| 64 | description of the proposed changes. For example, the RFC to modify a | ||
| 65 | few default Emacs things as a starting point for MMOSMacs is called | ||
| 66 | `RFC: Start with sensible defaults`. | ||
| 67 | |||
| 68 | The following template should be used when writing an RFC. | ||
| 69 | |||
| 70 | ```markdown | ||
| 71 | # Summary | ||
| 72 | |||
| 73 | Provide a one-paragraph summary of the proposed changes | ||
| 74 | |||
| 75 | |||
| 76 | # Rationale and motivation | ||
| 77 | |||
| 78 | Explain why this change is necessary or desirable. Relate to any other | ||
| 79 | relevant RFCs, Bug Reports, or Feedback. Feel free to link to Issues | ||
| 80 | from other repositories as well. | ||
| 81 | |||
| 82 | |||
| 83 | # Details | ||
| 84 | |||
| 85 | Provide an in-depth description of your proposed changes. This should | ||
| 86 | get into specifics and corner-cases. | ||
| 87 | |||
| 88 | |||
| 89 | # Drawbacks and Alternatives (optional) | ||
| 90 | |||
| 91 | Why should these changes NOT be implemented? What other options are | ||
| 92 | there, and why are these changes better than the alternatives? | ||
| 93 | |||
| 94 | |||
| 95 | # Additional resources (optional) | ||
| 96 | |||
| 97 | Link to external resources such as research papers, images, etc. | ||
| 98 | |||
| 99 | |||
| 100 | # Unresolved questions (optional) | ||
| 101 | |||
| 102 | Ask any further questions you have. | ||
| 103 | ``` | ||
| 104 | |||
| 105 | |||
| 106 | #### Creating branches & committing changes | ||
| 107 | |||
| 108 | All changes made as part of an RFC should be made in an associated | ||
| 109 | branch. The branch should be named in the format `TYPE/#/TITLE`, where | ||
| 110 | TYPE is one of `RFC, BUG`, X is the Issue number, and TITLE is a short | ||
| 111 | summary of the RFC title. For example the branch for | ||
| 112 | `RFC: Start with sensible defaults` is named `RFC/2/sensible-defaults`. | ||
| 113 | Branch names should be short, with an absolute maximum of 72 characters | ||
| 114 | (preferrably shorter). | ||
| 115 | |||
| 116 | Commits should be small and nuclear. They should each do "one thing". | ||
| 117 | That said, multiple files could theoretically be affected by a single | ||
| 118 | commit. Commit messages should be brief, but not omit any necessary | ||
| 119 | detail. | ||
| 120 | |||
| 121 | |||
| 122 | #### Writing a Pull Request | ||
| 123 | |||
| 124 | Like RFCs, all major changes to MMOSMacs must have an associated Pull | ||
| 125 | Reqest, which explains in detail the changes that were made. Pull | ||
| 126 | Requests are reviewed before the changes are accepted into the stable | ||
| 127 | branch, and it is likely that the reviewer will reject your changes with | ||
| 128 | notes on what needs to be fixed. | ||
| 129 | |||
| 130 | Pull Requests should explain the specifics and nuances of the changes | ||
| 131 | contained therein. | ||