Elegant release process is fully automated. It only works if all commit messages adhere to the set rules.
semantic-release uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next semantic version number, generates a changelog and publishes the release.
Basically, semantic-release goes through the commit messages, parses them and on its bases makes the decisions of publishing new release and new version number.
What are those rules?
Elegant development team chose to use Angular Commit Message Conventions.
Following portion is largely derived from their guidelines.
Reading, understanding and then getting used to following guidelines may take sometime.
Make your life easier and use Commitizen for Git commits. It automatically formats the commit message to conform to our guidelines.
Commit Message Format¶
Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>
The header is mandatory and the scope of the header is optional.
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.
If the commit reverts a previous commit, it should begin with
revert:, followed by the header
of the reverted commit.
In the body it should say:
This reverts commit <hash>., where the hash is the SHA of the commit
Must be one of the following:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing or correcting existing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
- use imperative, present tense: “change” not “changed” nor “changes” not “changing”
- don’t capitalize first letter
- no dot (.) at the end
What is Imperative mode¶
Here is a very good explanation of imperative mode.
Imperative mood just means “spoken or written as if giving a command or instruction”. A few examples:
- Clean your room
- Close the door
- Take out the trash
The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines.
- just as in use imperative, present tense: “change” not “changed” nor “changes”
- includes motivation for the change and contrasts with previous behavior
All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes.
feat(home): write about me in markdown, reST or asciidoc BREAKING CHANGE: Previously LANDING_PAGE_ABOUT was a dictionary that contained html tags. We used it to create landing page. But users have demanded from the very beginning to be able to write the landing page in markdown. This patch adds this feature. But in order to use it, you have to update your configuration. Closes #85
Closed bugs should be listed on a separate line in the footer prefixed with “Closes” keyword like this:
or in case of multiple issues:
Closes #123, #245, #992
In case your commit affects an issue, use “Updates” keyword
Following are few example commits that shows how Elegant has uses these guidelines.
feat(monetization): add BestAzon support feat(Chinese): add better font support for Chinese language feat(footer): make external links Nofollow
fix(reST): indents in line blocks is not preserved fix(gist): embedded Github gist are not laid out correctly
docs(add): metadata variables docs(add): release notes for 3.0.0 docs(update): change category of reading-time article docs(update): set author information
chore(livereload): use es2015 syntax for gulp configuration ci(docs): use sitemap plugin in production only ci(docs): add default tasks.py file refactor: move Google and Bing claims to their individual files
Examples of Incorrect Commit Messages¶
This commit message starts with a capital letter and ends with a period
doc(changes): Rewrite of multi-part plugin per issue 308.
This commit message does not use imperative mode.
docs(change): updating status doc to reflect current state