Forgejo release notes do not fit the popular trend that consists on enforcing conventional commits so that tools can collect them because:
- The unit of change in Forgejo is the pull request, not the commit. It is not uncommon for a pull request to contain multiple commits that are related but independent from each other. Squashing them into a single commit is not an option. There are diverging opinions on the matter and enforcing a merge policy where pull requests are always squashed into a single commit leads to a nicely flat commit history. But Forgejo made a different choice.
- A single commit or pull request may require multiple release note lines. When upgrading a dependency by modifying one line in the
go.mod file leads to user facing changes, each of them needs to be described in the release notes. Forgejo relies on hundreds of other Free Software projects and although most of them are plumbing that the Forgejo user do not need to be aware of, others are very visible such as the web editor.
- Release notes need manual editing. No matter how good and disciplined the author of a pull request is, there will be typos and unification problems that are best addressed when preparing the release, at the very last stage.
Discussions started early 2024 (here and there) to distribute the release notes workload to the author of each pull request rather than relying on a single person manually doing the same a few days before the release. As the number of contributors to Forgejo increased significantly early 2024, the quality of the v7.0.0 release notes was sub-standard and a solution had to be found.
The nuclear option would have been to enforce a merge policy that was a fit for the existing tooling. But even that would have not solved the case where a dependency upgrade needed multiple lines in the release notes so it was never considered to be a possibility.
With over a year of practice in publishing Forgejo releases and the associated release notes manually, the method to do that was well defined and stable. It was never really documented but looking at the discussions and pull requests it was not difficult to reverse engineer the workflow. There were some blurry technical points that were never solved because a human brain took a different path, such as figuring out the backport of a pull request based on the commits it contains. But the workflow itself was precise and it was not based on speculations, it was deduced from the making of over twenty releases.
This is the ideal situation when implementing a software: there is plenty of evidence that a human being did a number of things manually. The software just needs to do the same and automate as much as possible. There is no risk of over-engineering, as long as the developer does not get carried away and keeps it simple, stupid.
The release notes assistant was developed in that context, for the benefit of three type of users:
- The author of a pull request, to show them how their pull request will look in the final release notes so they can fine tune it
- The reviewer of a pull request, to ask for changes based on the result rather than the source
- The release manager, to collect them and allow manual editing in a single file before the release
A number of tools and actions in Forgejo, including some rather advanced are written in shell. But the complexity of the release notes assistant was above the threshold that would allow for long term maintenance. And the reasons are mainly:
- the logic to figure out which pull request is backported from which
- stable branches and how their history evolve in parallel with the development branch
It was decided to implement it in Go instead and has 90%+ test coverage. But the test environment which spawns a Forgejo instance with fixtures that mimic the structure of the Forgejo repository is derived from the existing end-to-end test framework and in shell.
The workflow added in the Forgejo repository is all the author and reviewers need to agree on a good enough release note.
The release manager still needs to use the tool manually and can, for instance, direct it to update the milestone, which was done for the Forgejo v7.0.6 release. And once the release is published, it could be added to the description of the release itself. Which would indirectly solve the rather annoying burden of maintaining a file in the repository with the same information.
In conclusion, although the release-notes-assistant was written to be generic and has nothing Forgejo specific, there is little chance it is actually used anywhere else. People won't discover it by chance and pushing it in this direction is not something anyone is ready to do at this point. Having a robust tool for publishing Forgejo and related projects is great. Maintaining a tool used by a variety of users with a whole range of needs is an entirely different proposition.
Note: Release notes lines written by the author of the pull request are good enough for point releases that need no explanation. But they should come with a companion blog post to provide context for major releases
Forgejo release notes do not fit the popular trend that consists on enforcing [conventional commits](https://www.conventionalcommits.org/) so that [tools](https://github.com/orhun/git-cliff) can collect them because:
* **The unit of change in Forgejo is the pull request, not the commit.** It is not uncommon for a pull request to contain multiple commits that are related but independent from each other. Squashing them into a single commit is not an option. There are diverging opinions on the matter and enforcing a merge policy where pull requests are always squashed into a single commit leads to a nicely flat commit history. But Forgejo made a different choice.
* **A single commit or pull request may require multiple release note lines.** When upgrading a dependency by modifying one line in the `go.mod` file leads to user facing changes, each of them needs to be described in the release notes. Forgejo relies on hundreds of other Free Software projects and although most of them are plumbing that the Forgejo user do not need to be aware of, others are very visible such as the web editor.
* **Release notes need manual editing.** No matter how good and disciplined the author of a pull request is, there will be typos and unification problems that are best addressed when preparing the release, at the very last stage.
Discussions started early 2024 ([here](https://codeberg.org/forgejo/discussions/issues/159) and [there](https://codeberg.org/forgejo/discussions/issues/155)) to distribute the release notes workload to the author of each pull request rather than relying on a single person manually doing the same a few days before the release. As the number of contributors to Forgejo increased significantly early 2024, the quality of the [v7.0.0 release notes](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/RELEASE-NOTES.md#7-0-0) was sub-standard and a solution had to be found.
The nuclear option would have been to enforce a merge policy that was a fit for the existing tooling. But even that would have not solved the case where a dependency upgrade needed multiple lines in the release notes so it was never considered to be a possibility.
With over a year of practice in publishing Forgejo releases and the associated release notes manually, the method to do that was well defined and stable. It was never really documented but looking at the discussions and pull requests it was not difficult to reverse engineer the workflow. There were some blurry technical points that were never solved because a human brain took a different path, such as figuring out the backport of a pull request based on the commits it contains. But the workflow itself was precise and it was not based on speculations, it was deduced from the making of over twenty releases.
This is the ideal situation when implementing a software: there is plenty of evidence that a human being did a number of things manually. The software just needs to do the same and automate as much as possible. There is no risk of over-engineering, as long as the developer does not get carried away and keeps it simple, stupid.
The [release notes assistant](https://code.forgejo.org/forgejo/release-notes-assistant) was developed in that context, for the benefit of three type of users:
* The author of a pull request, to show them how their pull request will look in the final release notes so they can fine tune it
* The reviewer of a pull request, to ask for changes based on the result rather than the source
* The release manager, to collect them and allow manual editing in a single file before the release
A number of tools and actions in Forgejo, including some [rather advanced](https://codeberg.org/forgejo/tools/src/commit/d158f39d2572ad7388a9744efdabaec614e6f1ae/scripts/weekly-cherry-pick.sh) are written in shell. But the complexity of the release notes assistant was above the threshold that would allow for long term maintenance. And the reasons are mainly:
* the logic to figure out which pull request is backported from which
* stable branches and how their history evolve in parallel with the development branch
It was decided to implement it in Go instead and has 90%+ test coverage. But the test environment which spawns a Forgejo instance with [fixtures that mimic the structure of the Forgejo repository](https://code.forgejo.org/forgejo/release-notes-assistant/src/commit/d7a2ee0fc6e43475b8790d69cd41392ac68c2703/tests.sh#L282-L371) is derived from the [existing end-to-end](https://code.forgejo.org/forgejo/end-to-end) test framework and in shell.
The workflow [added in the Forgejo repository](https://codeberg.org/forgejo/forgejo/src/commit/bca3f857dc4d420712f6314cde9b742d0017059e/.forgejo/workflows/release-notes-assistant.yml) is all the author and reviewers need to agree on a good enough release note.
The release manager still needs to use the tool manually and can, for instance, direct it to update the milestone, which was done for the [Forgejo v7.0.6 release](https://codeberg.org/forgejo/forgejo/src/commit/bca3f857dc4d420712f6314cde9b742d0017059e/.forgejo/workflows/release-notes-assistant.yml). And once the release is published, it could be added to the description of the release itself. Which would indirectly solve the rather annoying burden of maintaining a file in the repository with the same information.
In conclusion, although the release-notes-assistant was written to be generic and has nothing Forgejo specific, there is little chance it is actually used anywhere else. People won't discover it by chance and pushing it in this direction is not something anyone is ready to do at this point. Having a robust tool for publishing Forgejo and related projects is great. Maintaining a tool used by a variety of users with a whole range of needs is an entirely different proposition.
Note: Release notes lines written by the author of the pull request are good enough for point releases that need no explanation. But they should come with a companion blog post to provide context for major releases