Short guide to awesome changelogs

I've recently found one awesome changelog generator, based on your commit messages. That's git-changelog.

Git changelog comes with Grunt plugin and CLI. I am using CLI for generating changelogs, but Grunt plugin is also an awesome idea. It uses Angular JS commit standard (which is probably the best commit standard in my opinion), but you also have the ability to change that.

For installing git-changelog CLI, execute this command:

npm install -g git-changelog

How generated changelog looks like?

Here is an example of generated changelog: https://github.com/rafinskipg/git-changelog/blob/master/EXTENDEDCHANGELOG.md

How to configure `git-changelog`?

Here is an example of .changelogrc file that's used as configuration file:

{
    "app_name": "Git Changelog",
    "logo": "https://github.com/rafinskipg/git-changelog/raw/master/images/git-changelog-logo.png",
    "intro": "Git changelog is a utility tool for generating changelogs. It is free and opensource. :)",
    "branch" : "",
    "repo_url": "",
    "version_name" : "v1.0.0",
    "file": "CHANGELOG.md",
    "template": "myCustomTemplate.md",
    "sections": [
        {
            "title": "Bug Fixes",
            "grep": "^fix"
        },
        {
            "title": "Features",
            "grep": "^feat"
        },
        {
            "title": "Documentation",
            "grep": "^docs"
        },
        {
            "title": "Breaking changes",
            "grep": "BREAKING"
        },
        {
            "title": "Refactor",
            "grep": "^refactor"
        },
        {
            "title": "Style",
            "grep": "^style"
        },
        {
            "title": "Test",
            "grep": "^test"
        },
        {
            "title": "Chore",
            "grep": "^chore"
        },
        {
            "title": "Branchs merged",
            "grep": "^Merge branch"
        },
        {
            "title" : "Pull requests merged",
            "grep": "^Merge pull request"
        }
    ]
}

This is just a JSON file with a lot of properties. It's not required, if you don't insert it, it will use default settings (which is also ok for a nice changelog). You can find all properties on this link: https://github.com/rafinskipg/git-changelog#options--defaults

How commit message looks like?

So here we are. After you install git-changelog CLI and you setup .changelogrc file, you're ready to start committing in a proper way and generating your changelogs.

This plugin comes with a set of types:

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 or adds a feature
test: Adding missing tests
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

An example of a message of a commit that updates readme file:

git commit -m "docs(readme): Add documentation for explaining the commit message"

You see, just add any of type at the start of a commit message, then specify the exact feature that you worked on in brackets and give more information after two dots. Simple! This will increase commits readability.

Generating changelog

Now you have configuration and commits with specific message style. It's time to generate your changelog. That's really simple, just execute git-changelog command in your console:

git-changelog

That's all, your changelog will be saved in CHANGELOG.md file.

You can also use Grunt task for generating changelog, more information here: https://github.com/rafinskipg/git-changelog#grunt-task

Conclusion

git-changelog is an awesome library for teams and individuals. When you're working on projects, you want to know what stuff you changed, added or fixed. Writing proper commit messages increases readability and gives you the ability to create changelogs and track all changes in your code. Please try it, you will never regret!

Please leave a comment if you like this article! I would also like to know what plugins you use for generating changelogs and what commit message styles you prefer! 😊

Ivan Jovanovic