Problems & Background

Have you ever been frustrated by reading an app’s changelog that’s full of unhelpful information? It’s like they don’t care about their product or their users. You might have seen changelogs like this:

2.11.4

• Some bugs fixed

or

• Fix bugs and improve UI/UX

These changelogs are confusing and don’t provide any meaningful insights for users. Changelogs are meant for people, not machines. They serve as a way for us to communicate with our users. Whether you’re working on a big or small software project, it’s essential to create a useful changelog.

In the early stages, our commit messages were similar, not designed for humans, product teams, or even fellow engineers. They looked something like this:

🐞 Bugs

• Correct releaserc cfg (4337ccb)
• Disable webpage preview in tip message (1fe0fae)
• Remove extra @ in tip message (e6ac302)
• Sentry check ticker command (#64) (f81c9ca)

Initially, we didn’t see anything wrong with these messages; in fact, we considered them good. However, as time passed, we realized that we were missing essential context, such as which features, platforms, or affected areas these commits related to.

So, we decided to change the way we write commit messages and put in a bit more effort to enhance our notification platform. Now, with each release, we have clear and informative messages like this:

How

We’ve adopted a specific syntax when creating a new commit:

level(scope): message

• level: This indicates the nature of the change, such as a refactor, improvement, chore, fix, or feature.
• scope: This specifies which feature or area is affected by the changes.
• message: This is where we explain to users what they need to know about the update.

Checklist

• Focus on what matters most to users: new features, bug fixes, and improvements in terms of UI/speed.
• Write messages with users in mind, not just for fellow engineers.
• Always consolidate your PRs into a single commit to maintain a clean and coherent commit history.