We have previously discussed that our process of creating release notes at least for the Math/Stan/Cmdstan/Stanc3 is far from ideal.
In the Stan Math meeting yesterday we circled back to the idea @Stevo15025 proposed awhile back of using issue or PR fields for Release notes (https://github.com/stan-dev/math/issues/1357) and we feel we should go with that. We can start with Stan Math but I feel this should be done in all four repos.
So the proposal I will start implementing next week if there wont be any major objections here is:
- have a have a separate field in a Github PR template ( I explain why I prefer PRs over issues)
- implement a script that will collect those fields to make release notes
- update the release notes wiki page in Jenkins on all merges to develop. That will enable having up-to-date release notes and wont require manually running scripts before releases.
The PR submitter can leave the Release notes field empty if:
- the PR is fixing a bug that was introduced after the last release
- if the PR is part of a series of PRs that will implement a single feature
- its a continuous integration related PR (Jenkins/Travis fixes)
I prefer PRs over issues for the following reasons:
- we are not super careful with closing issues (we had a lot of fixed issues not closed in math/stan/cmdstan, stan is the most problematic in that terms right now with a lot of language issues that are either fixed or need to be transferred to stanc3)
- issues would require careful milestones labeling so we know if an issue was closed since the last release or befor that. That is doable and would be nice to have anyways, but I think its a bit unrealistic.
- we would need to add a release notes field to existing issues when we close them.
In theory and based on how Github is structured issues are more suitable for release notes but I think for practical purposes its going to be harder to achieve what we want with issues.
Any comments welcome.