If you are developing a library, tool, package, or virtually any software you probably make a lot of changes. With all these changes you will want to inform your users, how might you do that?

I will be going over as much information as I have about changelog methods and structures to compare my tool Changie with. That way you can come up with the best approach for your team, project, or organization.

Well, if you are building 'dev.to' you can publish Changelog posts describing all the new features directly. How else might you do it?

There are two things to consider here:

1. What format and method do we use for versions and changes
2. How we track and publish our changes

SemVer and Keep A Changelog

By far the most common method of versioning is semantic versioning. This is the preferred method if your project needs to keep some form of compatibility with previous versions. Alternatives are calver or my own hashver but for this article, I will be assuming semantic versioning.

The next question is how we format the changelog in a clear way. For that, the most common structure is Keep a Changelog. It is simple, clean, and well organized. There are other structures and creating your own is not too difficult so feel free to customize it a bit. The important part is that you have a cohesive structure and an easy-to-find place.

Tracking changes

When developing your features you will need to eventually include these in your changelog, how do you go about tracking all these before your release is ready?

Well, I have seen 3 different methods:

No tracking

Don't do any tracking and write your release notes when you release. The idea here is that... well ok not much of an idea really you just wait until you want to release then try and figure out all your changes from memory, maybe your completed issues or closed pull requests?

This tends to be the default as it is the "Do Nothing" approach. Of course, this often times translates to not having any changelog.

Commit Messages

Probably the most common option, or at least most readily available, is to pull your commit messages since the last release and package it all up. You have tools and formats such as conventional commits combined with standard version can auto-generate changelogs for you. NodeJS's changelog maker does the same thing in one package. GoReleaser has a built-in release notes tool that acts very similarly.

Using Files

The last method, and the method used by Changie, is to store "change files" in your repository while you are working on new features, bug fixes, or improvements. Then through some templating tool combining all these files into your CHANGELOG.md for users. Or at least something similar to that.

Examples include:

• Pythons Blurb It generating the What's New pages
• Gitlab's Changelog Entries which they explain why in the History section
• Twisted's Town Crier is a generic tool

Changie

Changie is a new tool very similar to Town Crier and the other file-based solutions with the intent of being customizable enough to fit any project's needs. It is also released as a single binary using Go so it should be easy to install on any machine.

What makes Changie unique

In keeping with the agnostic approach Changie aims to remove any language, tool, or framework requirements for changelog management. Creating binary releases for all platforms makes it easy to install no matter what language or tool your project is in (might need to add more but this is the goal). Changie is not a project requirement and will not be included in any dependency file. It is also not required for CI/CD like GitHub actions or Gitlab CI. Although, it can be integrated with them quite well. The latest command can be used to output your latest version for release generation.

Ability to customize a lot of the formatting outputs, with more options to come if needed.

Changie uses a prompt-based CLI that can be extended with additional choices. This system also includes validation options to check things are proper. More validation options will be added later but this already reduces typos and bad inputs.

Do you reference your version in multiple places? Update them all during your release process using replacements which is basically just a find and replace option.

Git is unused and not a requirement, you could use any source control on any platform and Changie would act the same way.

All these options and features allow you to run two commands (batch+merge), then create a pull or merge request. The result of this commit is a release-ready point with a new changelog and versioned release notes. You could use GitHub releases, GitLab releases, or publish them on a blog.

Note: Two commands are used here instead of one to allow you to include extra information with each release such as upgrade notes, more in-depth descriptions, or other release information not tied to a specific change.

For example, Changie uses itself for its own Changelog management. You can view the resulting CHANGELOG, changes directory and the GitHub release action publishing GitHub releases.

Benefits of Files over Commits

Using files may seem a little strange to those who have used commit messages or just written up changelogs before so I would like to include a few advantages of using them.

1. Separate information for developers and users: Developers care about technical details but users don't. If you have to pull both from commit messages it will be hard to make it clear. This will not matter if your tool is for developers but even then, some details are only impactful for internal developers.
2. Typos: If you have a typo in a commit message it will be pulled in for your changelog. If you fix it in the generated changelog it will still be wrong in the commit message. Using a file allows you to update it if you need to. You could also just remove it entirely if the feature was later removed before the release.
3. Reviews: Using a file allows you to include changelog updates as a part of your pull requests. This allows you to get reviews on the final output, especially helpful to get managers or tech writers to comment.
4. Customization: Using commit messages rely on a rather strict input and output system. Customizing these can be difficult if possible at all. Conventional changelog spec can be found here but if you wanted to add a new field it is not possible.
5. Use Any Commit Style: Using Changie does not restrict you from defining some commit style like standard commit or anything your team likes. But these are for developers only and should not be generated for your end-users. It also allows you to write smaller more concrete commits knowing each of them won't be part of the changelog.

Thanks for reading, if you are interested in trying Changie the guide is a good place to start.

Changie is of course open-sourced on GitHub. Feel free to comment or reach out on GitHub.