merge: #2731

2731: Replace conventional commits recommendation r=nickgerace a=nickgerace ## Commit Description Replace conventional commits recommendation with overall suggestions. An optional template is provided alongside examples. ## View Rendered Documents - [Preparing Your Changes](https://github.com/systeminit/si/blob/nick/eng-1922-replace-conventional-commits-recommendation-with-overall/docs/PREPARING_YOUR_CHANGES.md#commit-format) - [Contributing Guide](https://github.com/systeminit/si/blob/nick/eng-1922-replace-conventional-commits-recommendation-with-overall/CONTRIBUTING.md) ## GIF <img src="https://media4.giphy.com/media/h13YTf8R76VSfiBHDS/giphy.gif"/> Co-authored-by: Nick Gerace <[email protected]>
systeminit · Sep 7, 2023 · 4081581 · 4081581
2 parents 2be737b + 8e812a8
commit 4081581
Show file tree

Hide file tree

Showing 2 changed files with 55 additions and 8 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -41,8 +41,8 @@ Follow the following steps to ensure your contribution goes smoothly.
 1. [Fork](https://help.github.com/articles/working-with-forks/) the GitHub Repository allowing you to make the changes in your own copy of the repository.
 1. Create a [GitHub issue](https://github.com/systeminit/si/issues) if one doesn't exist already.
 1. Make the changes you would like to include, adding new tests where possible, and make sure all relevant existing [tests are passing](docs/RUNNING_RUST_TESTS.md).
-1. [Prepare your changes](/docs/PREPARING_YOUR_CHANGES.md).
-1. Ensure that your are in the [CONTRIBUTORS](CONTRIBUTORS.md) file (see the [Adding Yourself to the Contributors List](#adding-yourself-to-the-contributors-list) section for instructions)
+1. [Prepare your changes](/docs/PREPARING_YOUR_CHANGES.md) and ensure your commits are descriptive. The document contains an optional commit template, if desired.
+1. Ensure that you are in the [CONTRIBUTORS](CONTRIBUTORS.md) file (see the [Adding Yourself to the Contributors List](#adding-yourself-to-the-contributors-list) section for instructions)
 1. Create a pull request on GitHub. If you're new to GitHub, read about [pull requests](https://help.github.com/articles/about-pull-requests/). You are welcome to submit your pull request for commentary or review before it is complete by creating a [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests). Please include specific questions or items you'd like feedback on.
 1. A member of the System Initiative team will review your PR within three business days (excluding holidays in the USA, Canada, UK, and Brazil) and either merge, comment, and/or assign someone for review.
 1. Work with the reviewer to complete a code review. For each change, create a new commit and push it to make changes to your pull request. When necessary, the reviewer can trigger CI to run tests prior to merging.

diff --git a/docs/PREPARING_YOUR_CHANGES.md b/docs/PREPARING_YOUR_CHANGES.md
@@ -2,14 +2,61 @@
 
 This document contains information related to preparing changes for a pull request.
 
-## Committing
+## Commit Message Format
 
-We highly recommend following the [Convential Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) format when committing changes.
-Our prefixes are derived from the official specification as well as the those found in [commitlint](https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional), based on [Angular's commit conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md).
-When in doubt, use `feat`, `fix`, or `chore`!
+We do not require a particular commit message format of any kind, but we do require that individual commits be descriptive, relative to size and impact.
+For example, if a descriptive title covers what the commit does in practice, then an additional description below the title is not required.
+However, if the commit has an out-sized impact relative to other commits, its description will need to reflect that.
 
-Moreover, please sign your commits using `git commit -s`.
-You can amend an existing commit with `git commit -s --amend`, if needed.
+Reviewers may ask you to amend your commits if they are not descriptive enough.
+Since the descriptiveness of a commit is subjective, please feel free to talk to us [on Discord](https://discord.com/invite/system-init) if you have any questions.
+
+### Optional Commit Template
+
+If you would like an optional commit template, see the following:
+
+```text
+<present-tense-verb-with-capitalized-first-letter> <everything-else-without-puncutation-at-the-end>
+
+<sentences-in-paragraph-format-or-bullet-points>
+```
+
+Here is an example with a paragraph in the description:
+
+```text
+Reduce idle memory utilization in starfield-server
+
+With this change, starfield-server no longer waits for acknowledgement
+from the BGS API. As soon as the request is successful, the green
+thread is dropped, which frees up memory since the task is usually idle
+for ~10 seconds or more.
+```
+
+Here is another example, but with bullet points in the description:
+
+```text
+Replace fallout queue with TES queue
+
+- Replace fallout queue with TES queue for its durability benefits
+- Refactor the core test harness to use TES queue
+- Build and publish new TES queue Docker images on commits to "main"
+```
+
+Finally, here is an example with a more complex description:
+
+```text
+Use multi-threaded work queue operations in starfield-server
+
+Iterating through work queue items has historically been sequential in
+starfield-server. With this change, rayon is leveraged to boost overall
+performance within green threads.
+
+starfield-server changes:
+- Replace sequential work queue with rayon parallel iterator
+
+Test harness changes:
+- Refactor the core test harness to create an in-line work queue
+```
 
 ## Guide: Rebasing Your Changes