proposal for branch patches after first release

proposal for branch patches after first release

[Joel Brobecker]

Hello,

I would like to propose a change in our procedures when a patch gets
checked in a release branch.  This would only concern changes that
are made after the first release off that branch is made.

For instance, once we've made the GDB 7.6 release, any new patch on
the gdb_7_6-branch would be affected by this proposal.

The problem is the following:
  - The time it took to assemble the GDB 7.5.1 tarballs, and put
    them on both sourceware.org and gnu.org was under 30mins.
  - The amount of time it takes me to write the associated announcement
    was over 2 hours.

The reason for taking this amount of time is that I'd like to tell
everyone what it is exactly that 7.5.1 fixes over 7.5. For the first
major release (Eg 7.5), I can use the NEWS file, which provides
enough information. But for the 7.5.1, I have nothing other than
the revision log. So I went through every single commit, and tried
to write a small description for each commit (I skipped testsuite
changes to save time).

The proposal:

    Once a release has been published off a branch, any patch merged
    on the release branch requires a corresponding update in the
    NEWS file.

I think that it makes sense regardless of the problem that affects me
because, if someone feels strongly enough that the problem should
be fixed in a subsequent corrective release, I think it deserves
a NEWS entry. Also, it will allow users to refer to the NEWS files
to determine what exactly the corrective release fixes. And it will
save me tons of time because I can now write the annoucement using
the information there.

Technically, I think we'll want the NEWS update to be checked in
both HEAD + branch.  But I don't think we can add the entries in
the HEAD branch right away, because we don't know ahead of time
whether a corrective release will be made or not.  So what I propose
is the following: The NEWS entry should be checked in the branch.
And the Release Manager (me) will add those entries to the HEAD
when publishing the new release.

OK?

-- 
Joel

Re: proposal for branch patches after first release

[Eli Zaretskii]

> Date: Thu, 29 Nov 2012 15:14:15 +0100
> From: Joel Brobecker <brobecker@adacore.com>
> 
> The proposal:
> 
>     Once a release has been published off a branch, any patch merged
>     on the release branch requires a corresponding update in the
>     NEWS file.

That'd be a nuisance, IMO, because some of them might be
NEWS-unworthy.

An alternative would be to require some predictably formatted string
in the log entry or the commit message, which you then could grep for.

Yet another alternative would be to have a separate file, which
doesn't get into the tarball, with the relevant info, and request each
commit to the branch be accompanied with an entry for that file.

Re: proposal for branch patches after first release

[Pedro Alves]

On 11/29/2012 04:14 PM, Eli Zaretskii wrote:
>> Date: Thu, 29 Nov 2012 15:14:15 +0100
>> From: Joel Brobecker <brobecker@adacore.com>
>>
>> The proposal:
>>
>>     Once a release has been published off a branch, any patch merged
>>     on the release branch requires a corresponding update in the
>>     NEWS file.
> 
> That'd be a nuisance, IMO, because some of them might be
> NEWS-unworthy.

I agree.  And this results in a bit awkward NEWS file, in that we don't
normally document bug fixes there, but point releases are usually
only about bug fixes.

> An alternative would be to require some predictably formatted string
> in the log entry or the commit message, which you then could grep for.

A one line at the head would be quite standard, given people have come
used to mail subject == git commit summary.  This might be the easiest,
though making this a "branch-only" requirement is very error prone.

I wouldn't mind at all enforcing better and more self-contained commit
log style, FWIW.

> Yet another alternative would be to have a separate file, which
> doesn't get into the tarball, with the relevant info, and request each
> commit to the branch be accompanied with an entry for that file.

We could also make better use of bugzilla for this.  I had stated my opinion
on this <http://sourceware.org/ml/gdb-patches/2012-11/msg00395.html>:

"(...) I'm thinking more and more that we could get better
release notes if all bugfixes had PRs filed for the correspondent bugs.
At release time, we could find them in bugzilla, and say "this is the list
of bugs that has been fixed".  Other projects do this in their release
announcements (glibc even maintains a lists of fixed PRs in their NEWS, but
I'm not suggesting that), and I personally find it useful and interesting."

But I don't think this one is mutually exclusive with the commit log idea.

If people think the PR idea is too process burden for mainline, we could
require this only for fixes that go into a release branch.  E.g., tag
the PRs with a special tag, e.g. "in-7.6.1".

-- 
Pedro Alves

Re: proposal for branch patches after first release

[Joel Brobecker]

> > That'd be a nuisance, IMO, because some of them might be
> > NEWS-unworthy.
> 
> I agree.  And this results in a bit awkward NEWS file, in that we don't
> normally document bug fixes there, but point releases are usually
> only about bug fixes.

I agree it'd be pushing it for some commits (but I thought it'd
still be OK). Let's put that idea aside for now.

> > An alternative would be to require some predictably formatted string
> > in the log entry or the commit message, which you then could grep for.

> A one line at the head would be quite standard, given people have come
> used to mail subject == git commit summary.  This might be the easiest,
> though making this a "branch-only" requirement is very error prone.
> 
> I wouldn't mind at all enforcing better and more self-contained commit
> log style, FWIW.

While I agree it's a good idea to move towards this principle,
and for both head & branch, I think there is too much of a chance
for oversights.

> We could also make better use of bugzilla for this.  I had stated my opinion
> on this <http://sourceware.org/ml/gdb-patches/2012-11/msg00395.html>:
[...]
> If people think the PR idea is too process burden for mainline, we could
> require this only for fixes that go into a release branch.  E.g., tag
> the PRs with a special tag, e.g. "in-7.6.1".

Some of the commits in this release in fact did have a PR number,
and I was sometimes able to use that. But I noticed two issues:

  1. It takes time to process each commit, and then go through
     the various messages in the PR.

  2. Often, I will still have to look into the code itself to really
     figure out what the problem is. Take for instance PR gdb/14494
     (http://sourceware.org/bugzilla/show_bug.cgi?id=14494).  How
     do I quickly write up a description of the problem actually fixed?

I also think that having the information spread out, be it in
the revision logs, or in a bugs database, makes it hard for anyone
who wants to figure out what changes exactly a minor release
contains and for what purpose.

For all these reasons, I think that having the developer write up
the description himself, with approval from Eli, and put it somewhere
in a file, would be best. If we want to call it known-problems or
anything else, instead of putting that info in the NEWS files,
that would be fine as well.

-- 
Joel

Re: proposal for branch patches after first release

[Eli Zaretskii]

> Date: Thu, 29 Nov 2012 22:04:40 +0100
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> 
> > > An alternative would be to require some predictably formatted string
> > > in the log entry or the commit message, which you then could grep for.
> 
> > A one line at the head would be quite standard, given people have come
> > used to mail subject == git commit summary.  This might be the easiest,
> > though making this a "branch-only" requirement is very error prone.
> > 
> > I wouldn't mind at all enforcing better and more self-contained commit
> > log style, FWIW.
> 
> While I agree it's a good idea to move towards this principle,
> and for both head & branch, I think there is too much of a chance
> for oversights.

We post all patches here, most of them undergo a review before being
pushed, so we could keep an eye on that.  CVS allows one to change the
commit message, so we could do that retrospectively if someone forgets
(unless the git conversion will become confused by such changes).

If we keep these records on  ChangeLog, the fix is even simpler: just
make another commit with a proper description.

> I also think that having the information spread out, be it in
> the revision logs, or in a bugs database, makes it hard for anyone
> who wants to figure out what changes exactly a minor release
> contains and for what purpose.

This is an argument in favor of ChangeLog.

> For all these reasons, I think that having the developer write up
> the description himself, with approval from Eli, and put it somewhere
> in a file, would be best. If we want to call it known-problems or
> anything else, instead of putting that info in the NEWS files,
> that would be fine as well.

This, too, would be fine with me.

Re: proposal for branch patches after first release

[Pedro Alves]

On 11/29/2012 09:04 PM, Joel Brobecker wrote:
>>> That'd be a nuisance, IMO, because some of them might be
>>> NEWS-unworthy.
>>
>> I agree.  And this results in a bit awkward NEWS file, in that we don't
>> normally document bug fixes there, but point releases are usually
>> only about bug fixes.
> 
> I agree it'd be pushing it for some commits (but I thought it'd
> still be OK). Let's put that idea aside for now.
> 
>>> An alternative would be to require some predictably formatted string
>>> in the log entry or the commit message, which you then could grep for.
> 
>> A one line at the head would be quite standard, given people have come
>> used to mail subject == git commit summary.  This might be the easiest,
>> though making this a "branch-only" requirement is very error prone.
>>
>> I wouldn't mind at all enforcing better and more self-contained commit
>> log style, FWIW.
> 
> While I agree it's a good idea to move towards this principle,
> and for both head & branch, I think there is too much of a chance
> for oversights.

This would be about the equivalent of providing a git short log
on release announcements.  I guess we'll get there when we someday
switch away from cvs.

> 
>> We could also make better use of bugzilla for this.  I had stated my opinion
>> on this <http://sourceware.org/ml/gdb-patches/2012-11/msg00395.html>:
> [...]
>> If people think the PR idea is too process burden for mainline, we could
>> require this only for fixes that go into a release branch.  E.g., tag
>> the PRs with a special tag, e.g. "in-7.6.1".
> 
> Some of the commits in this release in fact did have a PR number,
> and I was sometimes able to use that. But I noticed two issues:
> 
>   1. It takes time to process each commit, and then go through
>      the various messages in the PR.
> 
>   2. Often, I will still have to look into the code itself to really
>      figure out what the problem is. Take for instance PR gdb/14494
>      (http://sourceware.org/bugzilla/show_bug.cgi?id=14494).  How
>      do I quickly write up a description of the problem actually fixed?

The idea is that you don't process the PRs at all.  You'd just give out
the numbers/summary, and perhaps an url.

Taking the e.g., of gcc's point release announcements, you'd get
something like:

GDB version 7.5.1 has been released.

GDB 7.5.1 is a bug-fix release containing fixes for regressions and serious
bugs in GDB 7.5.0, with over 20 bugs fixed since the previous release.  This
release is available from the FTP servers listed at:

  http://www.gnu.org/order/ftp.html

The list of bugs that have been fixed is:

    19745 - summary of PR (as recorded in bugzilla, and found by a simple search)
    22344 - gdb does foo when it should do bar

Or simply give a url to a search in bugzilla (or both).

(gcc release announcements don't list the bugs)

I've much ratter have more frequent and speedier point releases, than
worry about digesting the info too much.

> I also think that having the information spread out, be it in
> the revision logs, or in a bugs database, makes it hard for anyone
> who wants to figure out what changes exactly a minor release
> contains and for what purpose.

People that have been affected by some bug supposedly should have
gone to bugzilla and filed a bug, or added themselves to the CC list
of an existing bug.  That's what makes me believe that taking the
effort of writing a distilled summary might be more effort than necessary.

> For all these reasons, I think that having the developer write up
> the description himself, with approval from Eli, and put it somewhere
> in a file, would be best. If we want to call it known-problems or
> anything else, instead of putting that info in the NEWS files,
> that would be fine as well.

If we go this path, I'd like to say my comment against using NEWS might
have come out stronger than I intended.  In the end, you're doing
the releases and the announcements.  Myself, I'll do whatever you
prefer.

-- 
Pedro Alves

Re: proposal for branch patches after first release

[Doug Evans]

On Thu, Nov 29, 2012 at 6:14 AM, Joel Brobecker <brobecker@adacore.com> wrote:
> Hello,
>
> I would like to propose a change in our procedures when a patch gets
> checked in a release branch.  This would only concern changes that
> are made after the first release off that branch is made.
>
> For instance, once we've made the GDB 7.6 release, any new patch on
> the gdb_7_6-branch would be affected by this proposal.
>
> The problem is the following:
>   - The time it took to assemble the GDB 7.5.1 tarballs, and put
>     them on both sourceware.org and gnu.org was under 30mins.
>   - The amount of time it takes me to write the associated announcement
>     was over 2 hours.
>
> The reason for taking this amount of time is that I'd like to tell
> everyone what it is exactly that 7.5.1 fixes over 7.5. For the first
> major release (Eg 7.5), I can use the NEWS file, which provides
> enough information. But for the 7.5.1, I have nothing other than
> the revision log. So I went through every single commit, and tried
> to write a small description for each commit (I skipped testsuite
> changes to save time).
>
> The proposal:
>
>     Once a release has been published off a branch, any patch merged
>     on the release branch requires a corresponding update in the
>     NEWS file.
>
> I think that it makes sense regardless of the problem that affects me
> because, if someone feels strongly enough that the problem should
> be fixed in a subsequent corrective release, I think it deserves
> a NEWS entry. Also, it will allow users to refer to the NEWS files
> to determine what exactly the corrective release fixes. And it will
> save me tons of time because I can now write the annoucement using
> the information there.
>
> Technically, I think we'll want the NEWS update to be checked in
> both HEAD + branch.  But I don't think we can add the entries in
> the HEAD branch right away, because we don't know ahead of time
> whether a corrective release will be made or not.  So what I propose
> is the following: The NEWS entry should be checked in the branch.
> And the Release Manager (me) will add those entries to the HEAD
> when publishing the new release.

If it were me I'd just diff the ChangeLogs, write something based on
that (but not worry about being too detailed if it'll take too much
time to dig deeper), require bug numbers or whatever to be in the
ChangeLogs,
and leave it at that.

Re: proposal for branch patches after first release

[Joel Brobecker]

> If it were me I'd just diff the ChangeLogs, write something based on
> that (but not worry about being too detailed if it'll take too much
> time to dig deeper), require bug numbers or whatever to be in the
> ChangeLogs, and leave it at that.

In practice, many patches are often difficult to gauge, at least for me.
So this would be noticeably affecting the quality of the announcement,
to the point where I'd ask myself whether there might be any point in
going through the exercise at all.

All I need is a little help from the person the author, by ways of
a note, somewhere, explaining what it does. It doesn't matter as much
where the information is. It can be a "release notes" file, or even
the wiki. To me, it seems better to keep that information inside the
GDB sources, so I'd personally go with that.

-- 
Joel

Re: proposal for branch patches after first release

[Tom Tromey]

>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:

Pedro> We could also make better use of bugzilla for this.  I had stated
Pedro> my opinion on this
Pedro> <http://sourceware.org/ml/gdb-patches/2012-11/msg00395.html>:

Pedro> If people think the PR idea is too process burden for mainline, we could
Pedro> require this only for fixes that go into a release branch.  E.g., tag
Pedro> the PRs with a special tag, e.g. "in-7.6.1".

FWIW I wouldn't mind requiring a PR for each change on the branch.
If this gets too burdensome then we probably should be looking at a new
release anyway.

Tom