Gerrit

Edwin: how about a footer in the commit message, based on Google's practice; feasible for Gerrit?

Using the Topic might be too much overhead.

Sent an email to the maintainers mailing list to gain input on this:
https://groups.google.com/d/msg/gerritcodereview-maintainers/3LWYDwGW8Cw/Uo-32kOEDwAJ

[Empty comment from Monorail migration]

Summary from the discussion on the maintainer mailing list:

The maintainers agree that we want to enforce release note entries

There are several requirements for a solution:
1. Keep overhead for contributors as small as possible.
2. It must be self-explanatory for contributors to fulfill the release notes requirement.
3. It should be possible to keep track of release notes when merging branches or cherry-picking changes.
4. If release notes files are not directly updated, the release notes generation should be automatic.
5. Changes without release notes entries should be detected automatically.
6. Changes without release notes entries should be possible (as exception).
7. It should be possible to attribute several changes to the same release notes entry.
8. It should be easy for reviewers to review the release notes entry along with the change.
9. Submitting changes / merging branches should not require conflict resolution in release notes.

The following solutions have been discussed:

1. each change must be accompanied by a release notes change that has the same topic:

+ no release note generation needed
+ works well with merging branches
- quite large overhead for contributor
  * contributors must operate with 2 repositories
  * if change is moved to another branch, the release notes change must be updated manually
  * if a change is cherry-picked a new release notes change for the cherry-picked change has to be created manually
0 need linter / submit rule to detect changes that are not accompanied by a release notes change
+ reviewing release notes is easy
+ similar to how release notes updates are handled today
- prone to conflicts when submitting changes / merging branches

2. each change must have a release notes info in the commit message (a special paragraph at the end of the message):

+ works well with merging branches
+ works well with cherry-picking
- requires release note generation
+ little overhead for contributors
+ reviewing release notes is easy
- formatting options for release notes may be limited
0 need linter / submit rule to detect changes without release notes info in commit message
? How to support multiple changes that share a release notes entry?
  -> for the first iteration: just have the release notes in one of the changes,
      and say "N/A: <reason>" for the release notes entries of the other changes?

3. Have release notes in the gerrit repo and update them in the change:

- doesn't work well merging branches and cherry-picking if there are separate release notes files for different releases (one ever-growing release notes file might be possible)
- prone to conflicts when submitting changes / merging branches
+ reviewing release notes is easy
+ no release note generation needed
+ little overhead for contributors
0 need linter / submit rule to detect changes without release notes update

4. Have well-documented issues that allow release note generation, require each change to be linked to an issue:

- reviewing release notes is not easy because they are not part of the change (e.g. commenting not possible)
0 need linter / submit rule to detect changes without link to issue
? How are release note entries stored in the issues so that automatic release notes generation is possible?
- requires release note generation
+ little overhead for contributors
+ better documented issues
+ works well with merging branches
+ works well with cherry-picking

So far everyone prefers solution 2.

During the hackathon and user submit 2019 we discussed the possibility to use the reno tool from OpenStack [1] to generate release notes. By adapting reno we would not need to implement our own release notes generation. Compared to the solution that we have discussed so far it also would have the advantage that release note entries can be amended after they have been added and that there are more possibilities to do the formatting of the release note entries.

[1] https://docs.openstack.org/reno/latest/user/index.html

[Empty comment from Monorail migration]

> During the hackathon and user submit 2019 we discussed the possibility to use the reno tool from OpenStack [1] to generate release notes.

It seems that Reno has this design limitation: [1], quoting:

"
By comparison, reno does not currently support projects where development is spread across multiple active branches. In these situations, bug fixes are developed on the offending stable or release branch and this branch is later merged back into master. This is commonly referred to as a git-flow-based development workflow.

When this happens, reno has no way to distinguish between changes that apply to the given stable branch and those that apply to master. This is because reno is branch-based, rather than release-based. If your project uses this workflow, reno might not be for you.
"

Consider the case, where we have fixed critical bugs in ReviewDb or GWT UI code on stable-2.16 branch.
In that casde we would not be able to do it on master, and merge to stable-2.16, because there is no ReviewDb/GWT UI code on master any more.

* [1] https://docs.openstack.org/reno/latest/user/design.html

Thanks for raising this concern. My plan to go on with this issue is to write a design doc [1] that spells out our uses-cases, then consider the different possible solutions independently (one of them is using reno) and then come to a conclusion based on the pros & cons of the different solutions.

If reno doesn't fit our use-cases we should notice this during this process, as well as issues with any of the other solutions.

[1] https://gerrit-review.googlesource.com/Documentation/dev-design-docs.html

A first change for the design doc that describes the use-cases has been pushed:
https://gerrit-review.googlesource.com/c/homepage/+/239559

This was recently contributed by a colleague of mine, if I may introduce another input to this work:

[2] https://git.eclipse.org/r/#/c/144581/
<=> "skeleton: add create-new-and-noteworthy.py".

The description of the use-cases has been submitted:
https://gerrit-review.googlesource.com/c/homepage/+/239559

Unassigning this issue for now, as I'm not planning to work on any solution for this soon.

The below /recent reference [1] is proposing Commitizen [2], as a usable and handy tool to help get structured commit messages in. It seems like fitting with hooks if wanted, as well as co-automation of linting and changelog (>= partial release note) generation. -Would be worth a check I think once we resume the work on this issue.

[1] https://www.thoughtworks.com/radar/tools?blipid=201911081
[2] http://commitizen.github.io/cz-cli/

[Empty comment from Monorail migration]

[3] https://gerrit-review.googlesource.com/c/gerrit/+/284196

This change doesn't cover the whole of this scope, but could be a useful start.

Since [3] above, more work was done in that script which changed since, all merged by now (cf. [4] below).
-See [5] for the current backlog for that tool, prioritized. Shows current limitations too.

The tool is meant to help initialize release notes, which still require release management acts and other human amends.
Since 3.3 RC work [6], release_noter also introduced a slightly different release notes page template or structure.
That structure and its pre-automated content (supporting the ultimate, manual amends) remain an evolving WIP...

[4] https://gerrit.googlesource.com/gerrit/+/refs/heads/stable-3.3/tools/release_noter/
[5] https://bugs.chromium.org/p/gerrit/issues/list?q=component%3Atools%3Erelease_noter&can=2&sort=priority
[6] https://www.gerritcodereview.com/3.3.html

My hope is that this script and its supporting harness helps release managers initialize upcoming release notes.
I'm basically proposing that we keep improving [4] based on [5] and potentially more, to feed pages beyond [6].
The script can also be used to generate snippets to reuse within existing notes.

[7] https://gerrit-review.googlesource.com/c/gerrit/+/270193

[Empty comment from Monorail migration]

[Empty comment from Monorail migration]

Edits were made to reflect the following in Monorail: auto-CCs.