diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 323d0e19bc..333bf2d180 100644 --- 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 index 4a5f070fdd..e998af5b3c 100644 --- 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 + + + +``` + +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