[sane-devel] Upcoming changes for handling release notes

[Povilas Kanapickas]

Hi Allan,

On 12/30/21 1:21 AM, m. allan noah wrote:
> I don't recall this conversation, where did it take place?

I've proposed this twice during the last year:
https://alioth-lists.debian.net/pipermail/sane-devel/2021-August/039081.html

and also in a our private email chain between Olaf and the rest of
release-related people in January 2021 (title "Next release and packing
my bags", you were in the email thread too).

Anyway, ultimately this doesn't matter, because if you think the topic
needs further discussion, then the discussion needs to happen regardless.

> In the past, we had a Changelog that everyone modified for every merge,
> and it was largely a duplicate of their commit messages. So, we stopped
> doing it. Are you proposing a return to that type of duplication?

Partly.

I don't think we should duplicate commit messages. Release notes are for
end users, commit messages are for other developers, so good release
note and good commit message are completely different. It makes sense to
write a release note only if the change impacts end users in a
noticeable way. Many commits are refactorings and similar changes, so
they don't need a release note.

At the end of the day, if a backend developer does not think a release
note is needed, then we can just omit it. The worst that will happen is
that someone will double-check whether omission was not an oversight on
a merge request. Naturally, if release note is omitted, then the final
release notes will not mention the change.

Please let me know what you think.

Cheers,
Povilas
> On Wed, Dec 29, 2021 at 4:57 PM Ralph Little <skelband at gmail.com
> <mailto:skelband at gmail.com>> wrote:
> 
>     Hi,
> 
>     On 2021-12-29 1:30 p.m., Povilas Kanapickas wrote:
>     > Hello,
>     >
>     > There were some discussions on how to make handling release notes
>     easier
>     > in the past so that releases are not as difficult. Time has come to
>     > actually implement them.
>     >
>     > What changes?
>     >
>     > Developers will need to write a short one or two sentence
>     description to
>     > a new file in newsfragments directory when submitting the feature for
>     > review. That's it.
>     >
>     > Longer version:
>     >
>     > We'll write release notes as part of merge requests that introduce the
>     > features or bug fixes instead of deferring everything until the
>     release
>     > time comes.
>     >
>     > This has the benefit that the release notes will be written by a more
>     > knowledgeable person than the release manager and we will not wait
>     > months only to forget what merge request was actually about. The side
>     > benefit of this will be that creating releases will become easier
>     as no
>     > one will need to hunt all merge requests that comprise the release.
>     >
>     > The release notes for unreleased features will be stored in
>     > "newsfragments" directory in the repository. At the time of the
>     release,
>     > the files will be combined into a single text block, edited by the
>     > release manager and added to the NEWS file. Storing release notes in
>     > separate files before the release makes it easy to avoid merge
>     conflicts.
>     >
>     > Like I said above, for the developers almost nothing changes: just
>     add a
>     > new file to the newsfragments directory with a one sentence
>     description
>     > before creating a merge request.
>     >
>     > I've created a merge request with all unreleased changes since 1.0.32,
>     > you can see how the new process looks like in practice:
>     > https://gitlab.com/sane-project/backends/-/merge_requests/676
>     <https://gitlab.com/sane-project/backends/-/merge_requests/676>
>     >
>     > Regards,
>     > Povilas
>     >
>     Sounds great!
>     Will we clean this directory out on every release?
> 
>     Cheers,
>     Ralph
> 
> 
> 
> 
> 
> -- 
> "well, I stand up next to a mountain- and I chop it down with the edge
> of my hand"