|
18 | 18 | - [Output processing](#output-processing) |
19 | 19 | - [Coding standards](#coding-standards) |
20 | 20 | - [Commit message guidelines](#commit-message-guidelines) |
| 21 | + - [What does this mean for contributors?](#what-does-this-mean-for-contributors) |
| 22 | + - [What to know about Conventional Commits](#what-to-know-about-conventional-commits) |
21 | 23 | - [Unit tests](#unit-tests) |
22 | 24 | - [Continuous integration](#continuous-integration) |
23 | 25 | - [Documentation](#documentation) |
@@ -63,7 +65,8 @@ thoroughly as possible to describe the issue or feature request. |
63 | 65 | There is a three-step process for submitting code or documentation changes: |
64 | 66 |
|
65 | 67 | 1. [Commit your changes to a fork of |
66 | | - `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git) |
| 68 | + `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git) using [Conventional |
| 69 | + Commits](#commit-message-guidelines) |
67 | 70 | 2. [Create a pull request](#create-a-pull-request) |
68 | 71 | 3. [Get your pull request reviewed](#get-your-pull-request-reviewed) |
69 | 72 |
|
@@ -155,23 +158,81 @@ requirements: |
155 | 158 |
|
156 | 159 | ### Commit message guidelines |
157 | 160 |
|
158 | | -All commit messages must follow the [Conventional Commits |
159 | | -standard](https://www.conventionalcommits.org/en/v1.0.0/). This helps us maintain a |
160 | | -clear and structured commit history, automate versioning, and generate changelogs |
161 | | -effectively. |
| 161 | +To enhance our development workflow, enable automated changelog generation, and pave |
| 162 | +the way for Continuous Delivery, the `ruby-git` project has adopted the [Conventional |
| 163 | +Commits standard](https://www.conventionalcommits.org/en/v1.0.0/) for all commit |
| 164 | +messages. |
162 | 165 |
|
163 | | -To ensure compliance, this project includes: |
| 166 | +This structured approach to commit messages allows us to: |
164 | 167 |
|
165 | | -- A git commit-msg hook that validates your commit messages before they are accepted. |
| 168 | +- **Automate versioning and releases:** Tools can now automatically determine the |
| 169 | + semantic version bump (patch, minor, major) based on the types of commits merged. |
| 170 | +- **Generate accurate changelogs:** We can automatically create and update a |
| 171 | + `CHANGELOG.md` file, providing a clear history of changes for users and |
| 172 | + contributors. |
| 173 | +- **Improve commit history readability:** A standardized format makes it easier for |
| 174 | + everyone to understand the nature of changes at a glance. |
166 | 175 |
|
167 | | - To activate the hook, you must have node installed and run `bin/setup` or |
168 | | - `npm install`. |
| 176 | +#### What does this mean for contributors? |
169 | 177 |
|
170 | | -- A GitHub Actions workflow that will enforce the Conventional Commit standard as |
171 | | - part of the continuous integration pipeline. |
| 178 | +Going forward, all commits to this repository **MUST** adhere to the [Conventional |
| 179 | +Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits not |
| 180 | +adhering to this standard will cause the CI build to fail. PRs will not be merged if |
| 181 | +they include non-conventional commits. |
172 | 182 |
|
173 | | - Any commit message that does not conform to the Conventional Commits standard will |
174 | | - cause the workflow to fail and not allow the PR to be merged. |
| 183 | +A git pre-commit hook may be installed to validate your conventional commit messages |
| 184 | +before pushing them to GitHub by running `bin/setup` in the project root. |
| 185 | + |
| 186 | +#### What to know about Conventional Commits |
| 187 | + |
| 188 | +The simplist conventional commit is in the form `type: description` where `type` |
| 189 | +indicates the type of change and `description` is your usual commit message (with |
| 190 | +some limitations). |
| 191 | + |
| 192 | +- Types include: `feat`, `fix`, `docs`, `test`, `refactor`, and `chore`. See the full |
| 193 | + list of types supported in [.commitlintrc.yml](.commitlintrc.yml). |
| 194 | +- The description must (1) not start with an upper case letter, (2) be no more than |
| 195 | + 100 characters, and (3) not end with punctuation. |
| 196 | + |
| 197 | +Examples of valid commits: |
| 198 | + |
| 199 | +- `feat: add the --merges option to Git::Lib.log` |
| 200 | +- `fix: exception thrown by Git::Lib.log when repo has no commits` |
| 201 | +- `docs: add conventional commit announcement to README.md` |
| 202 | + |
| 203 | +Commits that include breaking changes must include an exclaimation mark before the |
| 204 | +colon: |
| 205 | + |
| 206 | +- `feat!: removed Git::Base.commit_force` |
| 207 | + |
| 208 | +The commit messages will drive how the version is incremented for each release: |
| 209 | + |
| 210 | +- a release containing a **breaking change** will do a **major** version increment |
| 211 | +- a release containing a **new feature** will do a **minor** increment |
| 212 | +- a release containing **neither a breaking change nor a new feature** will do a |
| 213 | + **patch** version increment |
| 214 | + |
| 215 | +The full conventional commit format is: |
| 216 | + |
| 217 | +```text |
| 218 | +<type>[optional scope][!]: <description> |
| 219 | +
|
| 220 | +[optional body] |
| 221 | +
|
| 222 | +[optional footer(s)] |
| 223 | +``` |
| 224 | + |
| 225 | +- `optional body` may include multiple lines of descriptive text limited to 100 chars |
| 226 | + each |
| 227 | +- `optional footers` only uses `BREAKING CHANGE: <description>` where description |
| 228 | + should describe the nature of the backward incompatibility. |
| 229 | + |
| 230 | +Use of the `BREAKING CHANGE:` footer flags a backward incompatible change even if it |
| 231 | +is not flagged with an exclaimation mark after the `type`. Other footers are allowed |
| 232 | +by not acted upon. |
| 233 | + |
| 234 | +See [the Conventional Commits |
| 235 | +specification](https://www.conventionalcommits.org/en/v1.0.0/) for more details. |
175 | 236 |
|
176 | 237 | ### Unit tests |
177 | 238 |
|
|
0 commit comments