Skip to content

Commit bf4d4cc

Browse files
jcouballjcouball
committed
docs: announce and document guidelines for using Conventional Commits
1 parent 880d38e commit bf4d4cc

File tree

2 files changed

+96
-49
lines changed

2 files changed

+96
-49
lines changed

‎CONTRIBUTING.md

Lines changed: 71 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@
1818
- [Output processing](#output-processing)
1919
- [Coding standards](#coding-standards)
2020
- [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)
2123
- [Unit tests](#unit-tests)
2224
- [Continuous integration](#continuous-integration)
2325
- [Documentation](#documentation)
@@ -63,7 +65,7 @@ thoroughly as possible to describe the issue or feature request.
6365
There is a three-step process for submitting code or documentation changes:
6466

6567
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 Commits
6769
2. [Create a pull request](#create-a-pull-request)
6870
3. [Get your pull request reviewed](#get-your-pull-request-reviewed)
6971

@@ -155,23 +157,79 @@ requirements:
155157

156158
### Commit message guidelines
157159

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.
160+
To enhance our development workflow, enable automated changelog generation, and pave
161+
the way for Continuous Delivery, the `ruby-git` project has adopted the
162+
**Conventional Commits** specification for all commit messages.
162163

163-
To ensure compliance, this project includes:
164+
This structured approach to commit messages allows us to:
164165

165-
- A git commit-msg hook that validates your commit messages before they are accepted.
166+
- **Automate versioning and releases:** Tools can now automatically determine the
167+
semantic version bump (patch, minor, major) based on the types of commits merged.
168+
- **Generate accurate changelogs:** We can automatically create and update a
169+
`CHANGELOG.md` file, providing a clear history of changes for users and
170+
contributors.
171+
- **Improve commit history readability:** A standardized format makes it easier for
172+
everyone to understand the nature of changes at a glance.
166173

167-
To activate the hook, you must have node installed and run `bin/setup` or
168-
`npm install`.
174+
#### What does this mean for contributors?
169175

170-
- A GitHub Actions workflow that will enforce the Conventional Commit standard as
171-
part of the continuous integration pipeline.
176+
Going forward, all commits to this repository **MUST** adhere to the [Conventional
177+
Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits not
178+
adhering to this standard will cause the CI build to fail.
172179

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.
180+
A git pre-commit hook may be installed to validate your conventional commit messages
181+
by running `bin/setup` in the project root.
182+
183+
#### What to know about Conventional Commits
184+
185+
The simplist convention commit is in the form `type: description` where `type`
186+
indicates the type of change and `description` is your usual commit message (with
187+
some limitations).
188+
189+
- Types include: `feat`, `fix`, `docs`, `test`, `refactor`, and `chore`. See the full list
190+
of types supported in [.commitlintrc.yml](.commitlintrc.yml).
191+
- The description must (1) not start with an upper case letter, (2) be no more
192+
than 100 characters, and (3) not end with punctuation.
193+
194+
Examples of valid commits:
195+
196+
- `feat: add the --merges option to Git::Lib.log`
197+
- `fix: exception thrown by Git::Lib.log when repo has no commits`
198+
- `docs: add conventional commit announcement to README.md`
199+
200+
Commits that include breaking changes must include an exclaimation mark before the
201+
colon:
202+
203+
- `feat!: removed Git::Base.commit_force`
204+
205+
The commit messages will drive how the version is incremented for each release:
206+
207+
- a release containing a **breaking change** will do a **major** version increment
208+
- a release containing a **new feature** will do a **minor** increment
209+
- a release containing **neither a breaking change or new feature** will do a
210+
**patch** version increment
211+
212+
The full conventional commit format is:
213+
214+
```text
215+
<type>[optional scope][!]: <description>
216+
217+
[optional body]
218+
219+
[optional footer(s)]
220+
```
221+
222+
- `optional body` may include multiple lines of descriptive text limited to 100 chars
223+
each
224+
- `optional footers` only uses `BREAKING CHANGE: <description>` where description
225+
should describe the nature of the backward incompatibility.
226+
227+
Use of the `BREAKING CHANGE:` footer flags a backward incompatible change even if it
228+
is not flagged with an exclaimation mark after the `type`. Other footers are allowed
229+
by not acted upon.
230+
231+
See [the Conventional Commits
232+
specification](https://www.conventionalcommits.org/en/v1.0.0/) for more details.
175233

176234
### Unit tests
177235

‎README.md

Lines changed: 25 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,31 @@
99
[![Documentation](https://img.shields.io/badge/Documentation-Latest-green)](https://rubydoc.info/gems/git/)
1010
[![Change Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/git/file/CHANGELOG.md)
1111
[![Build Status](https://github.com/ruby-git/ruby-git/workflows/CI/badge.svg?branch=master)](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI)
12-
[![Code Climate](https://codeclimate.com/github/ruby-git/ruby-git.png)](https://codeclimate.com/github/ruby-git/ruby-git)
13-
14-
* [Summary](#summary)
15-
* [v2.x Release](#v2x-release)
16-
* [Install](#install)
17-
* [Major Objects](#major-objects)
18-
* [Errors Raised By This Gem](#errors-raised-by-this-gem)
19-
* [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
20-
* [Examples](#examples)
21-
* [Ruby version support policy](#ruby-version-support-policy)
22-
* [License](#license)
12+
13+
- [📢 We've Switched to Conventional Commits 📢](#-weve-switched-to-conventional-commits-)
14+
- [Summary](#summary)
15+
- [Install](#install)
16+
- [Major Objects](#major-objects)
17+
- [Errors Raised By This Gem](#errors-raised-by-this-gem)
18+
- [Specifying And Handling Timeouts](#specifying-and-handling-timeouts)
19+
- [Examples](#examples)
20+
- [Ruby version support policy](#ruby-version-support-policy)
21+
- [License](#license)
22+
23+
## 📢 We've Switched to Conventional Commits 📢
24+
25+
To enhance our development workflow, enable automated changelog generation, and pave
26+
the way for Continuous Delivery, the `ruby-git` project has adopted the
27+
**Conventional Commits** specification for all commit messages.
28+
29+
**What does this mean for contributors?**
30+
31+
Going forward, all commits to this repository **MUST** adhere to the [Conventional
32+
Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits not
33+
adhering to this standard will cause the CI build to fail.
34+
35+
Read more about this change in the [Commit Message Guidelines section of
36+
CONTRIBUTING.md](CONTRIBUTING.md#commit-message-guidelines)
2337

2438
## Summary
2539

@@ -34,31 +48,6 @@ Get started by obtaining a repository object by:
3448

3549
Methods that can be called on a repository object are documented in [Git::Base](https://rubydoc.info/gems/git/Git/Base)
3650

37-
## v2.x Release
38-
39-
git 2.0.0 has recently been released. Please give it a try.
40-
41-
**If you have problems with the 2.x release, open an issue and use the 1.x version
42-
instead.** We will do our best to fix your issues in a timely fashion.
43-
44-
**JRuby on Windows is not yet supported by the 2.x release line. Users running JRuby
45-
on Windows should continue to use the 1.x release line.**
46-
47-
The changes in this major release include:
48-
49-
* Added a dependency on the activesupport gem to use the deprecation functionality
50-
* Create a policy of supported Ruby versions to support only non-EOL Ruby versions
51-
* Create a policy of supported Git CLI versions (released 2020-12-25)
52-
* Update the required Ruby version to at least 3.0 (released 2020-07-27)
53-
* Update the required Git command line version to at least 2.28
54-
* Update how CLI commands are called to use the [process_executer](https://github.com/main-branch/process_executer)
55-
gem which is built on top of [Kernel.spawn](https://ruby-doc.org/3.3.0/Kernel.html#method-i-spawn).
56-
See [PR #684](https://github.com/ruby-git/ruby-git/pull/684) for more details
57-
on the motivation for this implementation.
58-
59-
The `master` branch will be used for `2.x` development. If needed, fixes for `1.x`
60-
version will be done on the `v1` branch.
61-
6251
## Install
6352

6453
Install the gem and add to the application's Gemfile by executing:

0 commit comments

Comments
 (0)