Simplify creating release notes for Math/Stan(c3)/Cmdstan

Developers
1

We have previously discussed that our process of creating release notes at least for the Math/Stan/Cmdstan/Stanc3 is far from ideal.

Things were previously disucssed at least here, here and most recently here

In the Stan Math meeting yesterday we circled back to the idea @stevebronder 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.

1 Like
2

Why this exception? The other two make sense.

I think this makes a lot of sense though! Definitely seems easier to write release notes as we go than try to piece together whatever went into the code over the last three months.

I am happy to put the notes in pull requests or issues. Whatever makes the process easier. We can certainly change after 3 months if it doesn’t work out like we wanted.

1 Like
3

I think the reasoning is the following. Say that in the current release I write a new feature: this goes in the release notes, as expected. A week later we realise that there was a bug in it and we fix it: since the feature hasn’t been released yet, there’s no point in mentioning the bug.

2 Likes
4

Oooh, so fixing a bug for something never released doesn’t require issue notes. I see. Makes sense.