Moving Towards Better Release Notes:
- James Turnquist
This serves to make comments and recommendations on producing better release notes for RackHD as well as Katalist-based projects.
The goal is to provide better direction to the developer as to what is required for a suitable release note.
git client-side templates:
git clients support a commit template capability that is configurable through a 'git config' command. This would work OK except that the git configuration is not copied at the time of the clone. Developers would be required to properly configuration their local clones to use the template. This is not suitable for a code-base such as RackHD that has a variety of users each with varying degrees of git sophistication.
git server-side templates:
git provides server side 'hooks' that can perform a number of tasks based on the git request being made. This would be after the user has created their commit and is attempting to push their set of changes. Unfortunately, the commit history is already set at this point.
Github Pull Request templates (Recommended here)
In this model, the release note generation would key on the pull request comments. The developer would be shown a template and have the opportunity to write a single release note for their change.
github has a pull request template that can be added to the repository (in .github/PULL_REQUEST_TEMPLATE)
A sample pull request template might look like:
JIRA #: DESCRIPTION: TEST DESCRIPTION:
Any enforcement of the template would occur in the PR gate.
The following demonstrates how this might look for a developer.