ANNOUNCEMENT: ChangeLog policy change after GDB 11

ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Joel Brobecker]

Dear all,

Following the feedback received, and after discussion within
the group of GDB Global Maintainers, the following was decided:

  * GDB 11 will be the last release branch using ChangeLog files.

    Please continue providing ChangeLog entries as usual on master
    until we create the branch, and then on the gdb-11-branch.

  * On the master branch, once the gdb-11-branch has been created:

    - Stop requiring ChangeLog entries, neither in a ChangeLog file,
      nor in the commit message;

    - Continue requiring detailed commit messages, which give full
      context about the problem being addressed. The reviewers
      are encouraged to ask contributors to enhnace their commit
      messages if necessary (something we already do, but seems
      worth emphasizing).

    - To be implemented: Devise a mechanism which allows us to include
      in source packages a file with the list of changes made since
      the last release.

      Mostly for the record, one use case that was presented when
      requesting this feature was:

      | When looking at some 3rd party's gdb, to determine which
      | exact upstream GDB version the 3rd party based their version
      | on (so I could diff their local changes.)  Without a dump of
      | the commit logs, we won't have an equivalent standard record
      | for that.

      Exact method to automate the generation of that information
      has not been discussed. Anyone willing to help with that?

    - For patches with multiple authors, we ask that commits with
      multiple authors have a...

          Co-Authored-By: xxx

      ... git-trailer, so that complete author information be kept.

Note that this change of policy only concerns the code maintained
by the GDB project. Remember that the binutils-gdb repository,
as the name suggests, is shared between two projects, and that
this announcement doesn't concern the files maintained by the binutils
community.

We will find the best location to document this change of policy
momentarily.

-- 
Joel

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Mike Frysinger]

On 13 Jun 2021 08:10, Joel Brobecker wrote:
> Following the feedback received, and after discussion within
> the group of GDB Global Maintainers, the following was decided:

this is great news.  thanks for all your & other maintainers hardwork
that's gone into this.

> Note that this change of policy only concerns the code maintained
> by the GDB project. Remember that the binutils-gdb repository,
> as the name suggests, is shared between two projects, and that
> this announcement doesn't concern the files maintained by the binutils
> community.

can we summarize those dirs for clarity ?

these are obvious:
	gdb/
	gdbserver/
	gdbsupport/
	include/gdb/

i think also this one:
	gnulib/

and we're eager for sim to follow this policy:
	sim/
	include/sim/

does this include these since they aren't in the binutils release ?
	libdecnumber/
	readline/

any other dirs that i missed ?
-mike

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Pedro Alves]

On 2021-06-14 2:25 a.m., Mike Frysinger via Gdb-patches wrote:
> On 13 Jun 2021 08:10, Joel Brobecker wrote:
>> Following the feedback received, and after discussion within
>> the group of GDB Global Maintainers, the following was decided:
> 
> this is great news.  thanks for all your & other maintainers hardwork
> that's gone into this.
> 
>> Note that this change of policy only concerns the code maintained
>> by the GDB project. Remember that the binutils-gdb repository,
>> as the name suggests, is shared between two projects, and that
>> this announcement doesn't concern the files maintained by the binutils
>> community.
> 
> can we summarize those dirs for clarity ?
> 
> these are obvious:
> 	gdb/
> 	gdbserver/
> 	gdbsupport/
> 	include/gdb/
> 
> i think also this one:
> 	gnulib/
> 
> and we're eager for sim to follow this policy:
> 	sim/
> 	include/sim/
> 
> does this include these since they aren't in the binutils release ?
> 	libdecnumber/
> 	readline/
> 
> any other dirs that i missed ?

The top level MANTAINERS file is the canonical source to know which project owns which directory.

For the GDB project, we current have there:

 gdb/; gdbserver/; gdbsupport/; gnulib/; readline/; sim/; GDB's part of include/
         GDB: http://www.gnu.org/software/gdb/
         Patches to gdb-patches@sourceware.org.
         See also gdb/MAINTAINERS and sim/MAINTAINERS.

libdecnumber is owned by GCC, so no, it does not include that dir:

 libdecnumber/
         See libiberty.  The master copy of this directory is in the GCC
         repository.

Pedro Alves

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Simon Marchi]

On 2021-06-13 11:10 a.m., Joel Brobecker wrote:
>     - For patches with multiple authors, we ask that commits with
>       multiple authors have a...
> 
>           Co-Authored-By: xxx
> 
>       ... git-trailer, so that complete author information be kept.

Similar to that, I was wondering if we should define a standard method
to refer to a bug/PR number in a git trailer.  For example, for a commit
fixing an issue:

  Fixes: PR gdb/1234

Sometimes, you make a commit that is related to a PR but does not fix it
(for example, add a KFAIL-ed test).  In that case, it should be
something else than "Fixes".

What do people use normally for thse things?  Is it necessary, or just
mentioning "PR gdb/1234" somewhere in the commit message's free text
will be enough to automatically link the commit to the PR?

Simon

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 1359 bytes --]

> On 2021-06-13 11:10 a.m., Joel Brobecker wrote:
> >     - For patches with multiple authors, we ask that commits with
> >       multiple authors have a...
> > 
> >           Co-Authored-By: xxx
> > 
> >       ... git-trailer, so that complete author information be kept.
> 
> Similar to that, I was wondering if we should define a standard method
> to refer to a bug/PR number in a git trailer.  For example, for a commit
> fixing an issue:
> 
>   Fixes: PR gdb/1234
> 
> Sometimes, you make a commit that is related to a PR but does not fix it
> (for example, add a KFAIL-ed test).  In that case, it should be
> something else than "Fixes".

What about...

    Bug: PR gdb/1234

... or...

    Xref: PR gdb/1234

?

> What do people use normally for thse things?  Is it necessary, or just
> mentioning "PR gdb/1234" somewhere in the commit message's free text
> will be enough to automatically link the commit to the PR?

I believe so. FTAOD, here is the sequence in the script which
extracts the references to bugzilla PR numbers:

    while ($log_txt =~ m/\s(?:bug|PR|BZ)\s+\#?\s*(?:[a-z0-9+-]+\/)?(?:\/)?(\d+)(.*)$/si) {

Let me also attach a copy of the entire script, just in case I missed
something.

Regardless of the above, I think it would be nice if we used Git
trailers for this as it makes it easier to find that kind of information.

-- 
Joel

[-- Attachment #2: email-to-bugzilla --]
[-- Type: text/plain, Size: 3411 bytes --]

#!/usr/bin/perl
# -*-Perl-*-
#
# Perl filter to handle the log messages from the checkin of files in
# a directory.  This script will group the lists of files by log
# message, and mail a single consolidated log message at the end of
# the commit.
#
# This file assumes a pre-commit checking program that leaves the
# names of the first and last commit directories in a temporary file.
#
# Contributed by David Hampton <hampton@cisco.com>
#
# hacked greatly by Greg A. Woods <woods@web.net>
#
# Then chopped down just to send bugzilla email, for git.
use strict;

use POSIX;
use DBI;
use Mail::Header;
use Mail::Internet;

my $bugzillaproduct;

#
#	Subroutines
#
sub see_if_bugzilla_bug_exists {    
  my ($dbh, $product, $id) = @_;

  # Split $PRODUCT and SQL-ify.
  my $sql_product = '';
  for my $i (split (/\s+/, $product)) {
      if ($sql_product ne '') {
	  $sql_product .= ', ';
      }
      $sql_product .= "'" . $i . "'";
  }

  my $sth2 = $dbh->prepare ("SELECT COUNT(*) from bugs where bug_id = $id and product_id = any (select products.id from products where name in ($sql_product))") or return 0;
  $sth2->execute() or return 0;
  my $count = $sth2->fetchrow_array ();
  return $count > 0;
}

sub mail_bug_notification {
    my $name = shift;
    my $subject = shift;
    my $head = Mail::Header->new;
    $head->add('From', 'cvs-commit@gcc.gnu.org');
    $head->add('Subject', $subject);
    $head->add('To', $name);
    my $mail = Mail::Internet->new(Header => $head, Body => \@_);
    die "email send failed\n" if !$mail->send;
}

#
#	Main Body
#

# Initialize basic variables
#
my $debug = 0;

# Parse command line arguments.

while (my $arg = shift @ARGV) {
    if ($arg eq '-d') {
	$debug = 1;
	print STDERR "Debug turned on...\n";
    } elsif ($arg eq '-G') {
	die "Too many '-G' args\n" if $bugzillaproduct;
	$bugzillaproduct = shift @ARGV;
    }
}

# Used with sprintf to form name of Gnats notification mailing list.
# %s argument comse from -G option.
my $MAIL_FORMAT = '%s-bugzilla@localhost';

# Collect the body of the commit message.
binmode STDIN, ":utf8";
my @text = ();
while (<STDIN>) {
    push (@text, $_);
}

my $log_txt = join ('', @text);
my %done_ids = {};

# fche/jakub 2020-04-01 ... this following matches "Apr" and spams PR1
#while ($log_txt =~ m/[^Aa]?(?:bug|PR|BZ)\s+\#?\s*(?:[a-z+-]+\/)?(?:\/)?(\d+)(.*)$/si) {

while ($log_txt =~ m/\s(?:bug|PR|BZ)\s+\#?\s*(?:[a-z0-9+-]+\/)?(?:\/)?(\d+)(.*)$/si) {
    my $bug_id = $1;
    $log_txt = $2;
    if (!defined $done_ids{$bug_id}) {
	$done_ids{$bug_id} = 1;
	# Send mail to Bugzilla, if required.
	if ($bugzillaproduct ne '') {
	    my $dbh = undef;
	    if ($bugzillaproduct eq 'gcc') {
		$dbh = DBI->connect ("dbi:mysql:bugs", "swbugz", "everythingroses");
	    } else  {# elsif ($bugzillaproduct eq 'glibc')
		$dbh = DBI->connect ("dbi:mysql:sourcesbugs", "swbugz", "everythingroses");
	    }
	    if ($debug) {
		print STDERR "Attempting to see if bug $bug_id exists\n";
	    }
	    if (defined $dbh & see_if_bugzilla_bug_exists ($dbh, $bugzillaproduct, $bug_id)) {
		if ($debug) { print STDERR "It does\n"; }
		if ($bugzillaproduct ne 'gcc') {
		    mail_bug_notification( sprintf ($MAIL_FORMAT, "sourceware"), "[Bug $bug_id]", @text);
		} else { 
		    mail_bug_notification( sprintf ($MAIL_FORMAT, $bugzillaproduct), "[Bug $bug_id]", @text);
		}
	    }
	    $dbh->disconnect if defined $dbh;
	}
    }
}

exit 0;

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Simon Marchi]

On 2021-06-28 1:28 p.m., Joel Brobecker wrote:
> What about...
> 
>     Bug: PR gdb/1234
> 
> ... or...
> 
>     Xref: PR gdb/1234
> 
> ?

Regardless of the name of the trailer we choose, what if we put the URL
as the value:

  Fixes: https://sourceware.org/bugzilla/show_bug.cgi?id=1234

That makes it clickable, so it's much easier to go consult it.  If, for
some reason, the bugzilla URL changed, the bug number is still in the
URL, so we don't lose anything doing so.  We just lose the "component"
part, "gdb" in your example.  But I don't think it's important to have
it here in the commit message, it doesn't really give important
information.

Simon

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Luis Machado]

On 6/28/21 2:41 PM, Simon Marchi via Gdb-patches wrote:
> On 2021-06-28 1:28 p.m., Joel Brobecker wrote:
>> What about...
>>
>>      Bug: PR gdb/1234
>>
>> ... or...
>>
>>      Xref: PR gdb/1234
>>
>> ?
> 
> Regardless of the name of the trailer we choose, what if we put the URL
> as the value:
> 
>    Fixes: https://sourceware.org/bugzilla/show_bug.cgi?id=1234
> 
> That makes it clickable, so it's much easier to go consult it.  If, for
> some reason, the bugzilla URL changed, the bug number is still in the
> URL, so we don't lose anything doing so.  We just lose the "component"
> part, "gdb" in your example.  But I don't think it's important to have
> it here in the commit message, it doesn't really give important
> information.
> 
> Simon
> 

I like the idea of pasting the URL. It is indeed much easier to consult.

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Mike Frysinger]

On 28 Jun 2021 13:41, Simon Marchi via Gdb-patches wrote:
> On 2021-06-28 1:28 p.m., Joel Brobecker wrote:
> > What about...
> > 
> >     Bug: PR gdb/1234
> > 
> > ... or...
> > 
> >     Xref: PR gdb/1234
> > 
> > ?
> 
> Regardless of the name of the trailer we choose, what if we put the URL
> as the value:
> 
>   Fixes: https://sourceware.org/bugzilla/show_bug.cgi?id=1234

can we finally get shortlink redirects ?
  https://sourceware.org/bugzilla/1234
  https://sourceware.org/PR1234

just about every other bugzilla system i work with did this years ago.
-mike

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Hannes Domani]

 Am Dienstag, 29. Juni 2021, 03:11:19 MESZ hat Mike Frysinger via Gdb-patches <gdb-patches@sourceware.org> Folgendes geschrieben:

> On 28 Jun 2021 13:41, Simon Marchi via Gdb-patches wrote:
>
> > On 2021-06-28 1:28 p.m., Joel Brobecker wrote:
> > > What about...
> > >
> > >    Bug: PR gdb/1234
> > >
> > > ... or...
> > >
> > >    Xref: PR gdb/1234
> > >
> > > ?
> >
> > Regardless of the name of the trailer we choose, what if we put the URL
> > as the value:
> >
> >  Fixes: https://sourceware.org/bugzilla/show_bug.cgi?id=1234
>
>
> can we finally get shortlink redirects ?
>   https://sourceware.org/bugzilla/1234
>   https://sourceware.org/PR1234

Doesn't the second one work for you? It does for me.


Hannes

Re: ANNOUNCEMENT: ChangeLog policy change after GDB 11

[Mike Frysinger]

On 29 Jun 2021 10:07, Hannes Domani wrote:
> Am Dienstag, 29. Juni 2021, 03:11:19 MESZ hat Mike Frysinger Folgendes geschrieben:
> > On 28 Jun 2021 13:41, Simon Marchi via Gdb-patches wrote:
> > > On 2021-06-28 1:28 p.m., Joel Brobecker wrote:
> > > > What about...
> > > >
> > > >    Bug: PR gdb/1234
> > > >
> > > > ... or...
> > > >
> > > >    Xref: PR gdb/1234
> > > >
> > > > ?
> > >
> > > Regardless of the name of the trailer we choose, what if we put the URL
> > > as the value:
> > >
> > >  Fixes: https://sourceware.org/bugzilla/show_bug.cgi?id=1234
> >
> > can we finally get shortlink redirects ?
> >   https://sourceware.org/bugzilla/1234
> >   https://sourceware.org/PR1234
> 
> Doesn't the second one work for you? It does for me.

annoyingly, it does.  i had been testing /bugzilla/PR1234 to no avail.

would be nice if these links were more easily discoverable.  like if the
show_bug page itself used these links.  not sure bugzilla exposes these
as config options though.

at any rate, if we link to bugs in commit messages, imo using a URI is a
lot easier for people as it doesn't require unstated assumptions like
"what is a PR" and "what do i do with this string after PR".  i think
everyone knows what to do with a URI at this point.
-mike