You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The goal of this RFC is to determine whether adopting the Conventional Commits specification for commits targeting the master branch (or any other branch) is feasible for the NelmioApiDocBundle maintainer community. This is a continuation of a (very brief) discussion as part of #2261 which touched the aspect of commit messages.
Scope
As this repository's workflow is based on opening pull requests for changes targeting a specific branch (with very few direct pushes to the master branch, for example) the Conventional Commits specification will only have to be adopted for pull request titles, not individual commits within a pull request.1
Main benefits
Communicating the nature of changes to teammates, the public, and other stakeholders.
Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
See the following mockup of currently open pull requests for this repository compared to the current state, showcasing the quoted2 benefits:
Actual PR titles
Automatically generating CHANGELOGs.
This could potentially also be seen as a benefit, though implementing an automated changelog and release notes is out of scope of this RFC.
Implementation
Enforcing the Conventional Commits specification for pull request titles, while keeping the maintainer/contributor DX in mind, is achievable using a combination of two GitHub actions:
The following sample pull request showcases the validation/linting comment automatically created when an invalid title is presented: DominicLuidold#1. Once the title has been correctly updated, the comment will be automatically removed.
Tasks for successful implementation & usage of Conventional Commits
New GitHub Actions workflow linting GitHub pull request titles
Allow squash merging1 as only enabled merge option for pull requests3
Adapted commit message prefix4 for Dependabot pull requests
No direct commits to any branch without a pull request
The available list of scopes is currently unrestricted, could be configured to specifically enforcing mentioning one (ore more) GitHub issues with a #1234 syntax or any other string pattern that can be checked by a regex
Casing of the subject, e.g. has to start with an uppercase or lowercase character
While changing the approach, it may be beneficial to switch to using pull request title and description as default to use the PR's description as commit body rather than a list of commits that can be reviewed at any time looking at the merged PR. This approach is, for example, also used by Symfony itself. ↩
Adding a comment does not feel necessary in my opinion. The failing action-semantic-pull-request action in combination with a proper contributing guideline should be enough information to help guide a contributor to fixing their PR.
I don't see a reason to differ from the default. :)
The available list of scopes is currently unrestricted, could be configured to specifically enforcing mentioning one (ore more) GitHub issues with a #1234 syntax or any other string pattern that can be checked by a regex
I don't think we have to enforce creating an issue before creating a PR at this current time.
Casing of the subject, e.g. has to start with an uppercase or lowercase character
The goal of this RFC is to determine whether adopting the Conventional Commits specification for commits targeting the
master
branch (or any other branch) is feasible for the NelmioApiDocBundle maintainer community. This is a continuation of a (very brief) discussion as part of #2261 which touched the aspect of commit messages.Scope
As this repository's workflow is based on opening pull requests for changes targeting a specific branch (with very few direct pushes to the
master
branch, for example) the Conventional Commits specification will only have to be adopted for pull request titles, not individual commits within a pull request.1Main benefits
See the following mockup of currently open pull requests for this repository compared to the current state, showcasing the quoted2 benefits:
Actual PR titles
This could potentially also be seen as a benefit, though implementing an automated changelog and release notes is out of scope of this RFC.
Implementation
Enforcing the Conventional Commits specification for pull request titles, while keeping the maintainer/contributor DX in mind, is achievable using a combination of two GitHub actions:
A working proof of concept implementation can be found here: DominicLuidold@dd762d4.
The following sample pull request showcases the validation/linting comment automatically created when an invalid title is presented: DominicLuidold#1. Once the title has been correctly updated, the comment will be automatically removed.
Tasks for successful implementation & usage of Conventional Commits
Allow squash merging
1 as only enabled merge option for pull requests3Open discussion points
While the Conventional Commits specification is clear how a PR/commit should be written, the following aspects can be changed on a per project basis:
type
s is currently based on https://github.com/commitizen/conventional-commit-types but can be freely configuredscope
s is currently unrestricted, could be configured to specifically enforcing mentioning one (ore more) GitHub issues with a#1234
syntax or any other string pattern that can be checked by a regexsubject
, e.g. has to start with an uppercase or lowercase characterFootnotes
Based on the assumption that
Allow squash merging
is the only enabled merge option for pull requests, see Configuring commit squashing for pull requests ↩ ↩2https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits ↩
While changing the approach, it may be beneficial to switch to using
pull request title and description
as default to use the PR's description as commit body rather than a list of commits that can be reviewed at any time looking at the merged PR. This approach is, for example, also used by Symfony itself. ↩https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#commit-message ↩
The text was updated successfully, but these errors were encountered: