Skip to content

Commit

Permalink
Replace conventional commits recommendation
Browse files Browse the repository at this point in the history
Replace conventional commits recommendation with overall suggestions.
An optional template is provided alongside examples.

Signed-off-by: Nick Gerace <nick@systeminit.com>
  • Loading branch information
nickgerace committed Sep 7, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 2be737b commit 8e812a8
Showing 2 changed files with 55 additions and 8 deletions.
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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.
59 changes: 53 additions & 6 deletions docs/PREPARING_YOUR_CHANGES.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 8e812a8

Please sign in to comment.