|
1 | 1 | # Contribution Guidelines |
2 | 2 |
|
3 | | -These technical guidelines (mostly) apply to (most) [Open Tech |
4 | | -Strategies](https://opentechstrategies.com/) software projects. A |
5 | | -given project may extend or override these guidelines as needed. |
6 | | - |
7 | | -Please see also the [Code of Conduct](CODE_OF_CONDUCT), which applies |
8 | | -everywhere. |
9 | | - |
10 | | -## Standard Pull Request Model |
11 | | - |
12 | | -We use the typical "[merge |
13 | | -request](https://docs.gitlab.com/ee/user/project/merge_requests/)" |
14 | | -a.k.a. "[pull request |
15 | | -(PR)](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)" |
16 | | -development workflow. Below, we'll say "PR" for short. |
17 | | - |
18 | | -You're welcome to open a PR in any OTS repository. We encourage you |
19 | | -to first post about your plans either in an issue ticket (an existing |
20 | | -one or one you create) or in the appropriate discussion forum. That |
21 | | -discussion forum will vary from project to project. If you're not |
22 | | -sure where to find the right one, please ask on |
23 | | -[chat.opentechstrategies.com](https://chat.opentechstrategies.com/); |
24 | | -folks there will help steer you to the right place. |
25 | | - |
26 | | -By checking first, you can get any important design feedback or |
27 | | -suggestions before you start coding. It's also okay to ask questions |
28 | | -before you've decided whether or not you'll contribute a change. |
29 | | - |
30 | | -## Writing Commit Messages |
31 | | - |
32 | | -When composing a commit message, please use [these |
33 | | -guidelines](https://chris.beams.io/posts/git-commit/). The quick |
34 | | -summary is: |
35 | | - |
36 | | -* Limit the subject line to 50 characters |
37 | | -* Capitalize the first letter of the subject line, but... |
38 | | -* ...Do not end the subject line with a period |
39 | | -* Use the imperative mood in the subject line |
40 | | -* Separate subject from body with a blank line |
41 | | -* Wrap the body at 72 characters |
42 | | -* Use the body to explain _what_ and _why_ more than _how_ |
43 | | - |
44 | | -The reason for the short initial subject line is to support commands |
45 | | --- such as `git show-branch` -- that print summary lists of changes |
46 | | -showing just the first line of each commit message, usually prefixed |
47 | | -by some metadata on the left. (And the reason for leaving the period |
48 | | -off the subject line is thus to save space.) |
49 | | - |
50 | | -Think of the commit message is an introduction to the change. A |
51 | | -reviewer will read the commit message right before reading the diff |
52 | | -itself, so the commit message's purpose is to put the reader in the |
53 | | -right frame of mind to understand the code change. The level of |
54 | | -detail and specificity used in the message depends on the change. If |
55 | | -you're unsure, take a look at the repository's history, comparing |
56 | | -commit messages with the corresponding diffs, and use that as a guide. |
57 | | - |
58 | | -**Mention related issues:** If the commit is related to one or more |
59 | | -issue tickets, please mention each ticket number in the commit |
60 | | -message, like this: "issue #123". |
61 | | - |
62 | | -## Indentation and Whitespace |
63 | | - |
64 | | -Please uses spaces not tabs for indentation, and avoid trailing |
65 | | -whitespace. If a language has a standard indentation amount, use that |
66 | | -amount. E.g., indent Javascript code by 2 spaces per level, Python |
67 | | -code by 4 spaces, etc. |
68 | | - |
69 | | -This repository uses [EditorConfig](https://editorconfig.org/) to help |
70 | | -manage whitespace. Your IDE probably has an [EditorConfig plugin](https://editorconfig.org/#download). |
71 | | - |
72 | | -## Keep Unrelated Changes Separate |
73 | | - |
74 | | -Please put logically distinct changes into separate commits. For |
75 | | -example, this commit message -- although correctly formatted -- should |
76 | | -never happen: |
77 | | - |
78 | | -``` |
79 | | - Fix issue #51 latency bug; also, fix formatting |
80 | | - |
81 | | - Stop syncing to permanent storage on every write. That was causing |
82 | | - latency problems for clients who sent many files in a single request. |
83 | | - |
84 | | - Also, fix some longstanding formatting issues (trailing whitespace, |
85 | | - inconsistent indentation, etc) in the larger surrounding code block. |
86 | | -``` |
87 | | - |
88 | | -Even though one contiguous region of code was affected, there were |
89 | | -really two logically unrelated changes made to it. The better way |
90 | | -would be to first commit the formatting fixes by themselves, with a |
91 | | -commit message like this (a subject line is enough for a change like |
92 | | -this -- the commit message does not need a body): |
93 | | - |
94 | | -``` |
95 | | - Formatting fixes only; no substantive change |
96 | | -``` |
97 | | - |
98 | | -...and _then_ make the real change as a separate commit: |
99 | | - |
100 | | -``` |
101 | | - Fix issue #51 latency bug |
102 | | - |
103 | | - Stop syncing to permanent storage on every write. That was causing |
104 | | - latency problems for clients who sent many files in a single request. |
105 | | -``` |
106 | | - |
107 | | -Having the substantive change in its own commit means that now someone |
108 | | -reviewing the change can see exactly the relevant diff, without being |
109 | | -distracted by mere whitespace changes that don't affect the code's |
110 | | -behavior. This same reasoning applies even when the "other" change |
111 | | -isn't a whitespace-only change: it's much easier for a reviewer to |
112 | | -comprehend one change at a time than to try to comprehend multiple |
113 | | -changes mixed together. |
114 | | - |
115 | | -## Using Repository Templates |
116 | | - |
117 | | -Put standard repository templates in the root of the project, not in a |
118 | | -forge-specific subdirectory (e.g., not in a `.github/` subdirectory). |
119 | | - |
120 | | -By "standard repository templates", we mean files typically used in |
121 | | -most project repositories, such as `LICENSE.md`, `CONTRIBUTING.md`, |
122 | | -`PULL_REQUEST_TEMPLATE.md` or the `PULL_REQUEST_TEMPLATE/` directory, |
123 | | -and `ISSUE_TEMPLATE.md` or the `ISSUE_TEMPLATE/` directory. GitHub |
124 | | -originated such templates (see |
125 | | -[here](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors), |
126 | | -[here](https://github.blog/2016-02-17-issue-and-pull-request-templates/), |
127 | | -[here](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates), |
128 | | -[here](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository), |
129 | | -and |
130 | | -[here](https://docs.github.com/en/github/managing-your-work-on-github/about-automation-for-issues-and-pull-requests-with-query-parameters)), |
131 | | -but they are used elsewhere as well now. Whether a project is |
132 | | -hosted on GitHub or somewhere else, these files should work fine from |
133 | | -the root of the project. |
134 | | - |
135 | | -(GitHub's documentation mentions that certain templates offer optional |
136 | | -additional behaviors if-and-only-if they are located in the `.github/` |
137 | | -subdirectory. OTS projects do not rely on those additional |
138 | | -behaviors.) |
139 | | - |
140 | | -Having these files in the top directory of the project offers two main |
141 | | -advantages: |
142 | | - |
143 | | -1. New developers will see them more easily there. This is especially |
144 | | - important for `LICENSE.md` and `CONTRIBUTING.md`. |
145 | | - |
146 | | -2. The repository won't be forge-specific. This means that later if |
147 | | - the project decides to host elsewhere, less adjustment would be |
148 | | - needed. Possibly some of the templates wouldn't be useful at other |
149 | | - hosting forges, but that's okay; they can be ignored or used |
150 | | - manually. However, note that other forges |
151 | | - [tend to implement](https://github.com/go-gitea/gitea/issues/5488#issuecomment-449572640) |
152 | | - GitHub's functionality anyway, since GitHub has been a |
153 | | - standard-setter in this area. |
154 | | - |
155 | | -## Change Documentation and Tests Together With Code |
156 | | - |
157 | | -Whenever possible, please include related documentation updates and |
158 | | -test-suite updates directly in your change, i.e., in the same pull |
159 | | -request as the core source code change. |
160 | | - |
161 | | -## Fixing Security Vulnerabilities |
162 | | - |
163 | | -If your change fixes a security vulnerability that is not already |
164 | | -public knowledge, please report it privately (in whatever manner is |
165 | | -appropriate for that project) before discussing the change in any |
166 | | -public forums or posting a PR. |
167 | | - |
168 | | -### Expunging Branches Once They Are Merged |
169 | | - |
170 | | -In OTS repositories, once a branch has been merged to mainline we |
171 | | -usually delete the branch. This can be done via the web interface, or |
172 | | -from the command line: |
173 | | - |
174 | | - # Make sure you're not on the branch you want to delete. |
175 | | - $ git branch | grep '^\* ' |
176 | | - * main |
177 | | - |
178 | | - # No output from this == up-to-date, nothing to fetch. |
179 | | - $ git fetch --dry-run |
180 | | - |
181 | | - # Delete the branch locally, if necessary. |
182 | | - $ git branch -d some-now-fully-merged-branch |
183 | | - |
184 | | - # Delete it upstream. |
185 | | - $ git push origin --delete some-now-fully-merged-branch |
186 | | - |
187 | | -This only applies to branches in the repositories we manage, of |
188 | | -course. For your own repositories (including the ones that are cloned |
189 | | -from ours), you decide your own deletion policy, of course. |
190 | | - |
191 | | -## Handling license and copyright notices |
192 | | - |
193 | | -When creating a new project, put its open source license in a |
194 | | -top-level file called `LICENSE.md`. (Markdown versions of all the |
195 | | -usual open source licenses are easy to find on the Internet.) |
196 | | - |
197 | | -There is no need to put a copyright notice or license header in each |
198 | | -individual source file; the top-level `LICENSE.md` is sufficient for |
199 | | -our purposes. However, when we are modifying existing third-party |
200 | | -code -- e.g., when our project is based on a forked version of some |
201 | | -other project -- individual source files may already have copyright |
202 | | -notice lines and license headers blurbs. In those cases, leave the |
203 | | -existing copyright information intact, and just add a new copyright |
204 | | -line in each file that we change. For example: |
205 | | - |
206 | | -``` |
207 | | - Copyright (C) 1999 Upstream Third Party, Inc |
208 | | - Copyright (C) 2021 Open Tech Strategies, LLC |
209 | | -``` |
210 | | - |
211 | | -For third-party code that we redistribute together with our project, |
212 | | -leave all of its license information intact, of course, including any |
213 | | -`LICENSE` or `COPYING` or similar file. When we redistribute |
214 | | -third-party code, we are not changing its license nor claiming |
215 | | -copyright ownership of it; we are just another downstream user of the |
216 | | -code under whatever license it already has. |
217 | | - |
218 | | -## Effort Estimation |
219 | | - |
220 | | -We sometimes use **TSML** labels to estimate issue size: |
221 | | - |
222 | | -* **Tiny**: Trivial. E.g. fixing a typo in a string, or a color or a |
223 | | - minor layout issue on a page, or something like that. Typically |
224 | | - one does several tiny things in an hour, and it's the testing, |
225 | | - writing commit messages, etc, that takes the time. |
226 | | - |
227 | | -* **Small**: Like tiny but a bit bigger and a bit more complicated. |
228 | | - Might take up to half a day to fully wrap up, but at every step |
229 | | - it's obvious what to do. There is no need for much research, no |
230 | | - likelihood of non-trivial unexpected complications, etc. |
231 | | - |
232 | | -* **Medium**: Takes somewhere from half a day to two days. Might need |
233 | | - some investigation, and there is a possibility of unexpected |
234 | | - complications arising. |
235 | | - |
236 | | -* **Large**: Requires some thinking/research/investigation up front, |
237 | | - has a substantial chance of dragging in unexpected complications, |
238 | | - and takes multiple days or possibly a week or so. |
239 | | - |
240 | | -If something's really large, then we try to break it down into |
241 | | -subtasks, since it's hard to think of a thing that takes multiple |
242 | | -weeks as one single task -- although sometimes that can happen, for |
243 | | -example with a single unified change across an entire code base, like |
244 | | -changing from raw DB queries to using an ORM or something like that. |
245 | | - |
246 | | -## Strolls |
247 | | - |
248 | | -At OTS, we do "**strolls**". These are similar to what are called |
249 | | -"[sprints](https://en.wikipedia.org/wiki/Scrum_sprint)" in Agile/Scrum |
250 | | -terminology, but at the end of a stroll we feel energized and |
251 | | -refreshed, not tired and sweaty. |
252 | | - |
253 | | -Not all strolls necessarily have the same duration, even within the |
254 | | -same project. We choose a stroll's length based on the work to be |
255 | | -done, how everyone is feeling after immediately preceding strolls, and |
256 | | -what people's schedules look like during the upcoming stroll. |
257 | | - |
258 | | -(This section doesn't really belong here in `CONTRIBUTING.md`, of |
259 | | -course, since it's really about working style within OTS, not about |
260 | | -how to contribute to one of the open source projects we're responsible |
261 | | -for. We just put it here because we don't yet have another place for |
262 | | -it, and we wanted to be able to refer to it easily.) |
| 3 | +This is an Open Tech Strategies project and we follow the [Contribution Guidelines in the OTS Meta Repository](https://code.librehq.com/ots/meta/-/blob/main/CONTRIBUTING.md). |
0 commit comments