Automatic generation of Pharo project changelogs
Being a maintainer of multiple projects, and since I don’t want to die under administrative tasks, I use a few conventions in the projects I maintain allowing me to be more efficient.
Today, I will explain how I use those conventions to generate the beginning of my changelogs.
Everything that will be explained here works with Pharo 7 and the current version of Pharo 8 for projects hosted on GitHub.
How to contribute to be able to generate the changelog
First of all, to make use of some of Iceberg’s features, any contributions must start with an issue with an explicit title on GitHub.
Once the issue is created, it is time to start working on the problem/feature. To do this I retrieve a Pharo image, load the project and create a new branch to work on. To create the branch you must use the “New branch from issue” option. This option will allow you to create a branch with a name of the form “ISSUE_NUMBER-Name-of-the-issue”.
From that moment on it is possible to work on the branch and make commits for the new contribution.
Once the contribution is made, I use the “Create Pull Request…” option. This option will use the branch name as the name for the PR. This is important because the name of the pull request will be the first line of the commit message.
Note: I also add in the message a line `Fixes #ISSUE_NUMBER`. This will allow the associated issue to be closed when the PR merges in case the PR is addressed to the main branch of the project. (See: https://help.github.com/en/articles/closing-issues-using-keywords)
It is therefore possible to contribute several things in this way. Once I am ready to create a new version, thanks to my conventions, I can use small scripts to generate my changelog.
Generating the changelog
The first script is a git command to execute in a terminal (Git bash on windows).
In concrete terms, the command to generate the changelog for version v1.1.0 of my TinyLogger project:
REFERENCE_TO_ORIGIN can be a commit SHA or a tag to find the commit from which you want to generate the changelog.
This command generates me for example:
* Merge pull request #22 from jecisc/20-documentation-v110 ([e928f63](https://github.com/jecisc/TinyLogger/commit/e928f635134e2081c6a85f24adb7b11bd4261fdf))
* Merge pull request #21 from jecisc/18-Add-way-to-add-a-logger-only-if-not-already-existing ([ed94153](https://github.com/jecisc/TinyLogger/commit/ed94153d9f086fed3a4f801cfe2029db383514c6))
* Merge pull request #19 from jecisc/17-Add-pharo-8-to-ci ([2b7aded](https://github.com/jecisc/TinyLogger/commit/2b7adede42186b3aca18aea4c910421fc4b13558))
* Merge pull request #15 from jecisc/14-Add-way-to-initialize-remove-old-log-like-ensureDelete- ([6529cc8](https://github.com/jecisc/TinyLogger/commit/6529cc8a99360d93ad80a3badff5066021b6053f))
Then, I use this output as input for the next Pharo command:
It is necessary to replace ‘Content’ by the content generated by the previous command and now we get the beginning of a readable changelog:
* documentation v110 ([e928f63](https://github.com/jecisc/TinyLogger/commit/e928f635134e2081c6a85f24adb7b11bd4261fdf))
* Add way to add a logger only if not already existing ([ed94153](https://github.com/jecisc/TinyLogger/commit/ed94153d9f086fed3a4f801cfe2029db383514c6))
* Add pharo 8 to ci ([2b7aded](https://github.com/jecisc/TinyLogger/commit/2b7adede42186b3aca18aea4c910421fc4b13558))
* Add way to initialize remove old log like ensureDelete ([6529cc8](https://github.com/jecisc/TinyLogger/commit/6529cc8a99360d93ad80a3badff5066021b6053f))
Using this I can now produce my markdown file after some updates to arrange the items into categories:
Tips and future work
To have easy access to the code I add it to the top of my changelogs files in a comment. See: https://raw.githubusercontent.com/jecisc/TinyLogger/development/CHANGELOG.md
Currently, I manually arrange this generated changelog to structure it into sections (Bug fixes, Cleaning, New features, Infrastructure…). In the future maybe we could also generate that using new conventions.
