Message to all contributors: Release-Notes footer is now mandatory

[Luca Milanesio]

Dear Gerrit Community of contributors and maintainers,
I am communicating about a change in the submit rules on the Gerrit project on gerrit-review.googlesource.com (see [1] just merged).

What has changed
================

What is changing today is the requirement to merge a change. The author (or co-author) of a change needs to think *IF* and *HOW* the Change needs to be mentioned on the release notes of the forthcoming target release. The Change implemented with [1] is a low-tech solution to this problem requiring change authors to add a footer to the commit message specifying why a change is either not noteworthy or provide a single sentence description or link to mention in release notes.

Example of how a Change's commit message should look like now:

```
Introduce a new super-duper feature for reviewers

Implement a new super-duper feature that helps reviewers
understand what is worth reviewing and how to track the
progress.

Release-Notes: new super-duper feature for reviewers
Change-Id: I1019556e12e2477e82edf7fa63bda917cd011215
```

We intentionally do not create files or directories for release notes to keep the overhead at a minimum and avoid problems resulting from merging branches etc. With the commit message footer mechanism, release managers can use Git/Gerrit to find all new changes not contained in the prior release that don't say 'Release-Notes: skip' and compile the release notes based on that list.

Example of a Change's commit message that isn't worth mentioning in the release notes:

```
Fix a typo in public API javadoc

The term 'behaviour' was following the English spelling
whilst the Gerrit project follows the American spelling
rules.

Release-Notes: skip
Change-Id: I1019556e12e2477e82edf7fa63bda917cd011215
```

What hasn't changed
===================

The extra footer helps the release manager understand *what to include* in the release notes: the detailed description of the feature/modification remains in its repository, under the /pages/site/releases/<version>.md on the home page project [3] and the way to amend it, review and publish stays the same.

You are also encouraged to update the release notes document with more details about the Change introduced. However, that isn't blocking the submission of the Change and can be done later on when the feature is complete.

What do we want to achieve?
==========================

The Gerrit release notes had been created and reviewed too late in the process so far, causing potential delays and potential mistakes and gaps in the initial Gerrit versions. I believe many of you noticed that, and its consequences have caused trouble to many people.

We are making the check on *IF* and *HOW* a change impacts the release notes as part of the code review and approval.
We hope to make all the contributors and maintainers more active in this process and help prevent future mistakes and omissions.

— * —

Thank to everyone for the kind cooperation in making Gerrit releases better, more complete and documented.

Luca.

[1] https://gerrit-review.googlesource.com/c/gerrit/+/328235
[2] https://www.gerritcodereview.com/2022-01-12-esc-minutes.html#delay-in-gerrit-releases-due-to-the-review-of-release-notes
[3] https://gerrit.googlesource.com/homepage/+/refs/heads/master/pages/site/releases/

[Oswald Buddenhagen]

On Thu, Feb 10, 2022 at 10:51:02AM +0000, Luca Milanesio wrote:
>Release-Notes: new super-duper feature for reviewers
>

aaaaand ... we already have a case which shows why it isn't a very good
idea to make it a footer:
https://gerrit-review.googlesource.com/c/gerrit/+/330203
yep, the line is too long while the content is already pretty minimal.

in the qt project, we therefore use a special [ChangeLog] paragraph
instead. our commit template
(https://code.qt.io/cgit/qt/qt5.git/tree/.commit-template) mentions it
and there is a formal policy
(https://quips-qt-io.herokuapp.com/quip-0017-Change-log-creation.html).
our "sanity bot" verifies that it's used appropriately in relation with
footers, etc.
(https://code.qt.io/cgit/qt/qtrepotools.git/tree/git-hooks/sanitize-commit#n471
ff. for the masochists).

of course, "[ChangeLog] Skip" looks stupid, so using a footer for this
case still makes sense.

[Sven Selberg]

On Friday, February 11, 2022 at 4:15:51 PM UTC+1 oswald.bu...@gmx.de wrote:

On Thu, Feb 10, 2022 at 10:51:02AM +0000, Luca Milanesio wrote:
>Release-Notes: new super-duper feature for reviewers
>
aaaaand ... we already have a case which shows why it isn't a very good
idea to make it a footer:
https://gerrit-review.googlesource.com/c/gerrit/+/330203
yep, the line is too long while the content is already pretty minimal.

 

Commit message footer is admittedly not the ideal place to keep release-notes, since it's

one-line, but AFAICT that particular line is not close to any technical limitation.

[Oswald Buddenhagen]

On Sat, Feb 12, 2022 at 01:55:43AM -0800, Sven Selberg wrote:
>Commit message footer is admittedly not the ideal place to keep
>release-notes, since it's one-line, but

>AFAICT that particular line is not close to any technical limitation.
>

i don't expect there to be any technical limitation, except maybe the
one implicitly inherited from RFC5322 (which would be 1000).

but that misses the point - commit messages should be comfortably
viewable without reflowing, which is where the 72 column soft limit
comes from. it's fine to violate that for links and pre-formated text,
but not for flowed text.

[Luca Milanesio]

On 12 Feb 2022, at 09:55, Sven Selberg <sven.s...@axis.com> wrote:

On Friday, February 11, 2022 at 4:15:51 PM UTC+1 oswald.bu...@gmx.de wrote:

On Thu, Feb 10, 2022 at 10:51:02AM +0000, Luca Milanesio wrote:
>Release-Notes: new super-duper feature for reviewers
>
aaaaand ... we already have a case which shows why it isn't a very good
idea to make it a footer:
https://gerrit-review.googlesource.com/c/gerrit/+/330203
yep, the line is too long while the content is already pretty minimal.

 

Commit message footer is admittedly not the ideal place to keep release-notes, since it's

one-line, but AFAICT that particular line is not close to any technical limitation.

Exactly: the full technical detail of the release notes remains on the homepage repository and not in the commit message.

Luca.

in the qt project, we therefore use a special [ChangeLog] paragraph
instead. our commit template
(https://code.qt.io/cgit/qt/qt5.git/tree/.commit-template) mentions it
and there is a formal policy
(https://quips-qt-io.herokuapp.com/quip-0017-Change-log-creation.html).
our "sanity bot" verifies that it's used appropriately in relation with
footers, etc.
(https://code.qt.io/cgit/qt/qtrepotools.git/tree/git-hooks/sanitize-commit#n471
ff. for the masochists).

of course, "[ChangeLog] Skip" looks stupid, so using a footer for this
case still makes sense.

--
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/702526e6-7480-4587-bb95-7abda033ad20n%40googlegroups.com.

[Oswald Buddenhagen]

On Sat, Feb 12, 2022 at 12:31:19PM +0000, Luca Milanesio wrote:
>Exactly: the full technical detail of the release notes remains on the
>homepage repository and not in the commit message.
>

then you could just as well make the footer a boolean flag, and let the
RM compose the actual note based on the commit (message) themselves. i
did however gather the impression that this was about offloading the
work to the commit author. this requires that a (near-)finished release
note can be actually included in the commit message - in a
machine-readable format, yet without impairing the UX of humans.

[Luca Milanesio]

Not really off-loading my responsibility but rather have cooperation of the commit author in making the release notes more accurate and avoiding missing important commits / changes.
I will always have to rework and complete them, after the initial extraction from the commit messages.

Luca.

>
> --
> --
> To unsubscribe, email repo-discuss...@googlegroups.com
> More info at http://groups.google.com/group/repo-discuss?hl=en
>
> --- You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/Yge9hpCdgPV32HOp%40ugly.

[Oswald Buddenhagen]

On Sat, Feb 12, 2022 at 07:06:08PM +0000, Luca Milanesio wrote:
>I will always have to rework and complete them, after the initial
>extraction from the commit messages.
>

that is indeed our experience at qt, too, as devs tend to be bad at
context-switching to the different target audience. also, the raw output
tends to be somewhat incoherent even with the best input, as some
changes become obsolete, etc. nonetheless, providing better tooling to
"upstream" reduces the workload "downstream".

somewhat on a tangent, and probably not too important for a relatively
small project like gerrit, but you may find it interesting, or are even
aware of relevant tools: https://bugreports.qt.io/browse/QTQAINFRA-933
("need ChangeLog crowdsourcing platform").

[Nasser Grainawi]

Thanks for the link to that! I guess it’s not surprising that this is a common problem, but it’s disappointing that no good generic solutions seem to exist. The recent one you point to “reno”, looked good as I read through the design inputs, until I noted it does not support our current dev model of developing bug fixes on stable branches [2]. :-(

I think even if this first attempt with the Release-Notes footer ends up just being used to filter out the ’skips’, it will provide good value. We can always iterate and improve.

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

--
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

--- You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/YghN/jAAJkV6cTeQ%40ugly.

[Sven Selberg]

On Thursday, February 17, 2022 at 8:28:38 PM UTC+1 nas...@codeaurora.org wrote:

On Feb 12, 2022, at 5:17 PM, Oswald Buddenhagen <oswald.bu...@gmx.de> wrote:

On Sat, Feb 12, 2022 at 07:06:08PM +0000, Luca Milanesio wrote:

I will always have to rework and complete them, after the initial extraction from the commit messages.

that is indeed our experience at qt, too, as devs tend to be bad at context-switching to the different target audience. also, the raw output tends to be somewhat incoherent even with the best input, as some changes become obsolete, etc.  nonetheless, providing better tooling to "upstream" reduces the workload "downstream".

somewhat on a tangent, and probably not too important for a relatively small project like gerrit, but you may find it interesting, or are even aware of relevant tools: https://bugreports.qt.io/browse/QTQAINFRA-933
("need ChangeLog crowdsourcing platform").

Thanks for the link to that! I guess it’s not surprising that this is a common problem, but it’s disappointing that no good generic solutions seem to exist. The recent one you point to “reno”, looked good as I read through the design inputs, until I noted it does not support our current dev model of developing bug fixes on stable branches [2]. :-(

I think even if this first attempt with the Release-Notes footer ends up just being used to filter out the ’skips’, it will provide good value. We can always iterate and improve.

Naively it "shouldn't" be too difficult to come up with a standard for release-notes support in git using a notes ref to store release-notes for specific commits.
You wouldn't want to high-jack the current git-notes support as it would most likely collide with other features, but you could:
* add release-notes to a file named $SHA1~release-note in the same ref.
* Have a set format, the format in reno seems like a good candidate - https://docs.openstack.org/reno/latest/user/usage.html#editing-a-release-note

This would potentially allow for the release-manager to:
1. Gather the commits that constitutes this release ($PREVIOUS_RELEASE..$THIS_RELEASE).
2. Ask $TOOL for the release-notes for those commits
3. Lean back and watch the magic happen.

It would make it possible for services like Gerrit to develop View/UI Edit/validation/service of release-notes since they already talk git fluently.
You could still have a commit-message-footer that indicates whether release-notes should be present or not which would support the current

workflow, if no release notes should be added set to "false" if set to "true" a submit requirement is that there are release-notes present for the commit
(which possibly could be edited through a UI on the change-screen).
If the support is baked into cgit (like notes) you'll also have well spread universal CLI to the release-notes.

[Saša Živkov]

On Thu, Feb 10, 2022 at 11:51 AM Luca Milanesio <luca.mi...@gmail.com> wrote:

Dear Gerrit Community of contributors and maintainers,
I am communicating about a change in the submit rules on the Gerrit project on gerrit-review.googlesource.com (see [1] just merged).

What has changed
================

What is changing today is the requirement to merge a change. The author (or co-author) of a change needs to think  *IF* and *HOW* the Change needs to be mentioned on the release notes of the forthcoming target release. The Change implemented with [1] is a low-tech solution to this problem requiring change authors to add a footer to the commit message specifying why a change is either not noteworthy or provide a single sentence description or link to mention in release notes.

Example of how a Change's commit message should look like now:

```
Introduce a new super-duper feature for reviewers

Implement a new super-duper feature that helps reviewers
understand what is worth reviewing and how to track the
progress.

Release-Notes: new super-duper feature for reviewers

For one-liner release notes, in a lot of cases the commit message subject would be actually just copied to the release note line.

So,  why not support also something like:

Release-Notes: <subject>

Change-Id: I1019556e12e2477e82edf7fa63bda917cd011215
```

We intentionally do not create files or directories for release notes to keep the overhead at a minimum and avoid problems resulting from merging branches etc. With the commit message footer mechanism, release managers can use Git/Gerrit to find all new changes not contained in the prior release that don't say 'Release-Notes: skip' and compile the release notes based on that list.

Example of a Change's commit message that isn't worth mentioning in the release notes:

```
Fix a typo in public API javadoc

The term 'behaviour' was following the English spelling
whilst the Gerrit project follows the American spelling
rules.

Release-Notes: skip
Change-Id: I1019556e12e2477e82edf7fa63bda917cd011215
```

What hasn't changed
===================

The extra footer helps the release manager understand *what to include* in the release notes: the detailed description of the feature/modification remains in its repository, under the /pages/site/releases/<version>.md on the home page project [3] and the way to amend it, review and publish stays the same.

You are also encouraged to update the release notes document with more details about the Change introduced. However, that isn't blocking the submission of the Change and can be done later on when the feature is complete.

What do we want to achieve?
==========================

The Gerrit release notes had been created and reviewed too late in the process so far, causing potential delays and potential mistakes and gaps in the initial Gerrit versions. I believe many of you noticed that, and its consequences have caused trouble to many people.

We are making the check on *IF* and *HOW* a change impacts the release notes as part of the code review and approval.
We hope to make all the contributors and maintainers more active in this process and help prevent future mistakes and omissions.

— * —

Thank to everyone for the kind cooperation in making Gerrit releases better, more complete and documented.

Luca.

[1] https://gerrit-review.googlesource.com/c/gerrit/+/328235
[2] https://www.gerritcodereview.com/2022-01-12-esc-minutes.html#delay-in-gerrit-releases-due-to-the-review-of-release-notes
[3] https://gerrit.googlesource.com/homepage/+/refs/heads/master/pages/site/releases/

--
--
To unsubscribe, email repo-discuss...@googlegroups.com
More info at http://groups.google.com/group/repo-discuss?hl=en

---
You received this message because you are subscribed to the Google Groups "Repo and Gerrit Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to repo-discuss...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/repo-discuss/385988E0-F7D4-4BA7-8A66-02A6250B03AC%40gmail.com.

[Oswald Buddenhagen]

On Tue, Apr 05, 2022 at 09:58:02AM +0200, Saša Živkov wrote:
>So, why not support also something like:
>
>Release-Notes: <subject>
>

for consistency with "skip", that should also just take a bare word; i
suppose "copy" would be as pithy as it gets.

but note that the subject typically uses imperative, while release notes
should use a past tense. see also my "release note standards" thread
from 2022-03-04.