Everybody needs to add information about their work to the library’s changelog.
Ok, so you are working in a small team, creating a component library. Some people are fixing bugs, some are adding new functionalities and in general, there is one person working on a specific component. Seems like everything is okay and nobody is interfering with anybody’s work. But there’s one problem – we all need to collect information about our work in the library’s changelog.
The thing is that the changelog is a single file, which every member of the team needs to update. These updates create merge conflicts in git, so after merging one merge request to the master, suddenly the rest of them are having conflicts due to the fact that somebody put information about their change in the same line that everybody else did.
There are some ways to resolve this problem. First of all, you can add free ‘spots’ (https://about.gitlab.com/blog/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders) in your changelog and assign a number of them to each member of the team. As this should do the job, we found it rather more like a hack than a clean solution. Secondly, a changelog can be created based on your commit history. To get the most out of it and keep consistency among developers tools like commitizen (https://github.com/commitizen/cz-cli) come in handy. But the solution we chose took a different approach to the problem.
Read also: Spring Boot REST application with Keycloak SSO integration
It was introduced on GitLab’s blog (https://about.gitlab.com/blog/2018/07/03/solving-gitlabs-changelog-conflict-crisis/) and it is fantastic. The concept relies on the principle that every developer adds information about their change in a separate .md file in a ‘release’ folder. Each file name is the ID of the issue in Jira, that asks about a bugfix or a feature. When release day comes, we run our special node script, that reads all of the files, adds the ID of the issue to the end of each line in a file and finally joins all the information to the changelog. Moreover, the number of the current release is passed down as an argument to the script like this:
`npm run update-changelog — 2.1.1`
Of course, there is some room for improvement. For example, instead of giving a specific number of release, our script could accept a string ‘patch’, ‘minor’ or ‘major’ and come up with a proper number based on the prior release. Moreover, the running script could be added to the release pipeline in GitLab so everything would work automatically.
All in all, there are many ways to keep the changelog. Some may argue that it should be based on commit history, some will say that having placeholders in the changelog file works and there is no need to complicate things. And I can say something too – since we have adapted the concept of separate files, keeping the changelog has never seemed so painless for us.
Read also: Orchestration: the machines can do the work
