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. | ||