Every SaaS company will sooner or later get to a stage of their growth where it becomes harder and harder to keep everyone in all departments up to date on what’s happening on a product level.
Ambassify is no exception, which is why we tried to find the most suitable solution for the problem at hand.
In this case, we thought it would be awesome to have something that ties into our current working method with GitHub, and that’s where our idea of a changelog came from.
Making changes to a development process that almost feels like muscle memory is tricky, so it was essential to keep the extra work for the devs to a minimum to give this a chance of becoming a new habit.
A changelog should just be a simple overview of the implemented changes with a short explanation, sometimes accompanied by a screenshot to illustrate the change.
At Ambassify, we follow a standard GitHub workflow. We write a changelog for each issue that impacts the customer experience in the form of an issue comment. This changelog comment has the format shown below:
Once an issue is resolved or closed, we automatically run a script in our changelog repository that searches all CHANGELOG prefixed comments and publishes them on a website.
Do note that we only search for changelog comments in closed issues. Doing this makes it possible for a developer to write a changelog for their issue already while their pull request is still in review or staging.
What’s the stack?
The changelog page is created using Jekyll, a static website generator.
The script will look for changelog comments with a more recent date than the newest changelog found during the previous run. We create a Jekyll post for each newly-found changelog comment.
The next step is to build Jekyll with all up-to-date changelog posts in place.
This static website is then published to a GitHub page to which we have attached a custom domain name. In our case, this is changelog.ambassify.com.
We also create an RSS feed of all changes. This makes it possible to load our changelog in Slack to keep everyone in the team informed about new product changes.
What about commit messages?
However, it depends on the target audience using your changelog. For our use case, these changelogs should also be understandable for prospects that maybe have never seen the product before. For us, it was essential to work with images and other markups to give the reader a clear visual overview of the change.
In our case, this simple solution resulted in a lot of saved communication time. To give you some examples:
- Your Marketing department will stay up to date about new features in the platform that they can write and publish content about or use for targeted ads.
- Your Customer Success team will be updated on new features and bug fixes to communicate with relevant customers.
- Customers can get quick and immediate updates about features launched just minutes before.
- If a prospect is waiting for a new feature to be released before signing the contract, the Sales team can immediately send a link to that specific change.
- You can link a specific feature in discussions with co-workers on Slack. That doesn’t seem like a big deal, but it helps get everyone on the same page during product discussions.
Is this the best implementation of a changelog? No, probably not. Not at all. But if we look at the saved time versus effort, this is a great solution that makes a difference.
We are working on an open-source solution for this project that would allow you to roll this out for your GitHub organization by just doing a simple repository fork. We believe that this can help many SaaS companies regardless of the product they are building.