I don’t mind to have a release notes section with prs…please do not make this obligatory… that’s my only request here. Otherwise it’s a good idea.
Should we disallow the C++20 keywords updated here as well?
https://en.cppreference.com/w/cpp/keyword
I think they all are
char8_t
concept
consteval
constinit
co_await
co_return
co_yield
requires
Why not? imo it could just be a one-liner answer for, “What does this PR do?”
If the majority wants that… ok. I am not a fan of more obligatory formalities, we already have a lot of them. Maybe the default entry in such a spot can “minor impact”?
But maybe we just need to put it there and everyone wants to show what a great contribution went in…and will proudly fill it out. So that would probably be a motivating thing then…
Maybe we dont put it as mandatory to not be too pedantic for cleanup and refactor PRs that dont necessarily need to be mentioned in release notes. I do feel that reviewers of PRs that have a larger effect should require the changes to be listed.
The alternatives is what we have now, that someone has to go through all PRs before the release and check what was changed which is a huge effort and can easily lead to stuff not being mentioned in the release notes.
I dont see this as something to show off with rather to list all the major changes that could otherwise go unnoticed. I dont see it being a huge additional effort. You already need to write what your PR is changing in the top-level PR comment. This would just require pasting that one-liner to a file.
EDIT:
You dont need to be very detailed or fancy in this text. Just a simple one liner. Those responsible for the actual release can go and do some copy editing if required.
1 Like
I think so. Could you open an issue in stanc3?
What about putting a field in the PR template as discussed in Add ## Release Notes to the PRs template · Issue #1357 · stan-dev/math · GitHub?
2 Likes
That is also fine with me, though I think the “News.md” approach has a few additional benefits.
It would be an improvement to what we have now, so I am fine with that if others feel that the PR comment field is better.
PR comment field is probably a bit easier for the PR submitter. The drawbacks I see is that we still need to write a script to go through the PRs to collect it.
With the file approach you also have a list of features on develop at any given time. Though the value of that is probably debatable.
1 Like
The main problem with NEWS.md is with conflicts, which in the current setup would cause an additional test cycle. If we bypass the CI when we change that file, then I’d be fine too with having it for bugfixes and non- trivial changes.
1 Like
Yes, we definitely implement this once we have the CI bypass for non-src files. Without it, it would be painful with conflicts, no doubt.
This issue is independent of that. Every time we add a new function to the language we’ve technically broken backward compatibility. It’s just a coincidence that Aki’s complaint was coincident with stanc3—it could’ve come on any of our releases of stanc in the past.
I’m in favor of doing that.
I disagree. If this is going to work to produce our release notes, it has to be obligatory. Otherwise, it’s just pushing the work back on whoever does the release and they won’t be in nearly as good a position to write these notes as the person writing the PR.
This is a user-facing feature, not a developer-facing one. If there’s no user-facing change, then nothing needs to go in the release notes. But if there is a user-facing change, that’s exactly what we’re trying to doc. We want to do this to give users like Aki a heads up about what’s changed release to release. We try to do it by looking at PRs, issues, and comit messages, which is very inaccurate.
I’m not sure what the intention of that name is, but I’d prefer to keep this at the level of simple release notes, not press releases. For instance, when the offset/multiplier stuff went in, that’d be something like:
* new reserved words: offset, multiplier
* linearly transformed parameters, e.g., real<offset = mu, multiplier = sigma> for natural non-centered parameterizations
1 Like
No intention, Release-notes.md is fine with me. News.md was just an example name I found in a repo I was looking at that moment. The short example you give is what I am proposing. Short, to the point. Whoever is responsible for the release can then copy edit a fancier text if required.
1 Like
+1 the last time I wrote the release notes I had to go through each PR and be like, “Well the byline for this PR seems like it would be <stuff>”
2 Likes