Skip to content
This repository has been archived by the owner on Feb 28, 2020. It is now read-only.

Commit format documentation

Jump to bottom
Christian Compton edited this page Aug 24, 2018 · 6 revisions

The content here applies to all IBM-Swift, IBM-developer, and ARF yeoman generators.

Message format

The message format is important for automatic release versioning and changelog generation

The change summary (the first line of the commit and the pull request title) should look like one of the following:

  • feat: your message -- use this for features
  • fix: your message -- use this for bug fixes
  • test: your message -- use this for adding missing tests or fixing existing tests
  • docs: your message -- use this for changes that only affect documentation
  • chore: your message -- use this for changes that do not affect the shipped code, like Travis config changes

Make the message descriptive, it will be used in the change log!

You may also add a topic in parenthesis before the colon, here are some examples:

  • chore(travis): add node 8 to testing matrix
  • docs(readme): add Travis badge
  • feat(deps): yeoman-generator@0.23.3

Important - Any breaking change should include the following in the commit message separated from the summary by a blank line:

BREAKING CHANGE: reason for the breaking change

My pull request failed validation and linked me here

To ensure each pull request, when merged, correctly identifies the category of change for Semantic versioning we use the standard-version module. This uses the first line of the commit message to determine whether the change is a feature or bug fix, and the body for whether there is a breaking change.

  • If your pull request has only one commit, then ensure that the commit follows the message format.
  • If your pull request has multiple commits, then ensure the title of the pull request follows the message format.
  • If your pull request contains a breaking change, then ensure one of the commits contains a BREAKING CHANGE: message marker as described in the message format.

Purpose

These rules will allow the automatic release scripts to prepare a release of the generator for each merged feature. This should significantly reduce the effort to make a release.

These rules allow the release script to determine the correct version update for the release and to update the change log.

The Feature Process describes how feature branches and pull requests are used for developing changes. They are merged into the develop branch using the github "Squash and merge" button. The commit linter attempts to review the feature pull request before it is merged to check if the default summary will match the message format rules above.

The person performing the merge must be careful to use a correct title and message body when confirming the Squash and merge (github gives an opportunity to edit the summary and body) as it will not be checked. Follow the Feature Process and the message format to determine the correct way to merge. Quick summary:

  • do ensure there's a good summary message for the change log
  • don't change the summary in the title box of the Squash and merge
    • if you need to change it: edit the PR title (if multiple commits) or the commit message (if one commit) so the linter can check it
  • do ensure any BREAKING CHANGE lines are preserved and are at top of the main comment box
  • do clean up the main comment to remove lines from transitory commits (like fix commits that happened along the way to the solution, leave only lines that summarise chunks of the final squashed change)

Automatic releases

The release script will create a branch based on develop from after the feature was merged. Then it will:

  • Bump the version in the package.json
  • Update the change log (CHANGES.md)
  • Protect the branch
  • Create a release pull request to master

At this point, the release pull request can be reviewed to ensure it looks good.

If the release pull request is not good, it can be closed and the protected branch will automatically be deleted. A new release pull request will be created when the next feature is merged.

If the release pull request is good, it can be merged with the github "Create merge commit" button and the scripts will tag and publish the new release.

Automatic version update

The release script will use standard-version to update the package version according to the information provided in the squashed feature commit.

  • A commit with a BREAKING CHANGE will cause a major version update
  • A feat commit will cause a minor version update
  • Any other commit will cause a patch version update

If there are multiple commits in the release, only one version update will occur based on the highest category. For example, if there is a fix and feat commit, then it will cause a minor version update.

This is following the standard-version format.

Clone this wiki locally