Re: [gentoo-dev] Summary line (was: Re: Referencing bug reports in git)

[Alec Warner]

On Tue, Aug 11, 2015 at 7:35 AM, Kent Fredric  wrote:

> On 12 August 2015 at 02:28, Ian Stakenvicius  wrote:
> > Stuff like 'cat/pn: version bumps', 'cat/pn: new features', 'cat/pn:
> > adjusted dependencies' are generic (and short) enough yet descriptive
> > enough to see what went on while scanning the log.
>
> I personally find those summaries a bit too terse.
>

Summaries are supposed to be terse, they are summaries ;)


>
> Mostly, because when I see "A version is bumped" I immediately expect
> to know which version the bump is to, but have to dig out the diff to
> find out.
>
>
So I thought we used to have scripts that would dig out this information
and populate them in headers?

-A


> I would also prefer, where possible, to replace "adjusted
> dependencies" to be more concise, like "include dev-perl/Foo in
> dependencies", ( though of course, apply some taste, listing more than
> 3 distinct new dependencies in the summary is execessive, treat them
> like hashtags on twitter, 1 is good, 2 is OK, 3 and you're starting to
> get crazy )
>
> > Multi-package commits are going to be more of an issue of course..  I
> > did one last night, fortunately I think I can get away with using
> > "mozilla packages" in place of cat/pn since it is a very specific set
> > of packages.  Perhaps for sweeping changes like that we can use the
> > herdname or projectname or the category name (if its a particular
> > category only)?
>
> Agreed. If you need multi-package changes and you can't think of a
> good category prefix to use, the commit message should visibly
> acknowledge that its a multi-package commit of some kind, and the
> *kind* of change should be very clear.
>
> Just keep in mind really the recommendations for prefix naming are
> descriptive, not prescriptive, and interpretation and good taste need
> to be applied everywhere.
>
>
>
> --
> Kent
>
> KENTNL - https://metacpan.org/author/KENTNL
>
>

Re: [gentoo-dev] Summary line

[Michael Orlitzky]

On 08/31/2015 01:33 PM, Rich Freeman wrote:
> On Mon, Aug 31, 2015 at 10:53 AM, Alec Warner  wrote:
>>>
>>> Mostly, because when I see "A version is bumped" I immediately expect
>>> to know which version the bump is to, but have to dig out the diff to
>>> find out.
>>>
>>
>> So I thought we used to have scripts that would dig out this information and
>> populate them in headers?
>>
> 
> Rather than embedding info about the content of the commit into the
> headers, wouldn't it make sense to just obtain it from git on-demand?
> Maybe you want to run git whatchaged instead of git log, or use one of
> the bazillion different log pretty formats, or define your own?
> 

Yes, `git log --stat` tells me what I want `git log` to tell me.

[gentoo-dev] Summary line (was: Re: Referencing bug reports in git)

[Ian Stakenvicius]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 11/08/15 04:57 AM, Tobias Klausmann wrote:
 The more we stuff into the summary line, the harder it will be to 
 write meaningful summaries. And thus, people will write crappy ones
 or ignore the length limit. I recommend against any more 
 prescription over Add the the cat/pn if meaningful, don't use more
 than 75 characters.
 
 The cat/pn rule is tricky anyway: what if one commit touches 100 
 packages? Or should that be split into 100 commits for easier 
 partial rollback?
 
 Regards, Tobias
 


The summary line limit is going to be a real issue, tbh.  I think it
would probably be best to adopt the convention of putting a few
choice, perhaps even canned, phrases in the summary line, and ensure
any and all details (effectively what the summary line used to be for
when it had practically no limit) within the commit message body instead
.

Stuff like 'cat/pn: version bumps', 'cat/pn: new features', 'cat/pn:
adjusted dependencies' are generic (and short) enough yet descriptive
enough to see what went on while scanning the log.  'Fix bug' IMO in
the summary doesn't work at all because, although its accurate, that
bug could literally be anything at all.

Multi-package commits are going to be more of an issue of course..  I
did one last night, fortunately I think I can get away with using
mozilla packages in place of cat/pn since it is a very specific set
of packages.  Perhaps for sweeping changes like that we can use the
herdname or projectname or the category name (if its a particular
category only)?


-BEGIN PGP SIGNATURE-
Version: GnuPG v2

iF4EAREIAAYFAlXKBpIACgkQAJxUfCtlWe3pQgD8Ct1elGvDIObKKvskQJ1jCZIK
cYvuWdMD7pobr/hH6iIA/jnYirAb9CDe4iNlVPqG2AKYbj9NJdGnpoL/TFhJtj8U
=vnTb
-END PGP SIGNATURE-

Re: [gentoo-dev] Summary line (was: Re: Referencing bug reports in git)

[Kent Fredric]

On 12 August 2015 at 02:28, Ian Stakenvicius a...@gentoo.org wrote:
 Stuff like 'cat/pn: version bumps', 'cat/pn: new features', 'cat/pn:
 adjusted dependencies' are generic (and short) enough yet descriptive
 enough to see what went on while scanning the log.

I personally find those summaries a bit too terse.

Mostly, because when I see A version is bumped I immediately expect
to know which version the bump is to, but have to dig out the diff to
find out.

I would also prefer, where possible, to replace adjusted
dependencies to be more concise, like include dev-perl/Foo in
dependencies, ( though of course, apply some taste, listing more than
3 distinct new dependencies in the summary is execessive, treat them
like hashtags on twitter, 1 is good, 2 is OK, 3 and you're starting to
get crazy )

 Multi-package commits are going to be more of an issue of course..  I
 did one last night, fortunately I think I can get away with using
 mozilla packages in place of cat/pn since it is a very specific set
 of packages.  Perhaps for sweeping changes like that we can use the
 herdname or projectname or the category name (if its a particular
 category only)?

Agreed. If you need multi-package changes and you can't think of a
good category prefix to use, the commit message should visibly
acknowledge that its a multi-package commit of some kind, and the
*kind* of change should be very clear.

Just keep in mind really the recommendations for prefix naming are
descriptive, not prescriptive, and interpretation and good taste need
to be applied everywhere.



-- 
Kent

KENTNL - https://metacpan.org/author/KENTNL

Re: [gentoo-dev] Summary line

[Mikle Kolyada]

11.08.2015 17:36, hasufell пишет:
 On 08/11/2015 04:28 PM, Ian Stakenvicius wrote:
 On 11/08/15 04:57 AM, Tobias Klausmann wrote:
 The more we stuff into the summary line, the harder it will be to 
 write meaningful summaries. And thus, people will write crappy ones
 or ignore the length limit. I recommend against any more 
 prescription over Add the the cat/pn if meaningful, don't use more
 than 75 characters.
 The cat/pn rule is tricky anyway: what if one commit touches 100 
 packages? Or should that be split into 100 commits for easier 
 partial rollback?
 Regards, Tobias


 The summary line limit is going to be a real issue, tbh.  I think it
 would probably be best to adopt the convention of putting a few
 choice, perhaps even canned, phrases in the summary line, and ensure
 any and all details (effectively what the summary line used to be for
 when it had practically no limit) within the commit message body instead
 .

 Stuff like 'cat/pn: version bumps', 'cat/pn: new features', 'cat/pn:
 adjusted dependencies' are generic (and short) enough yet descriptive
 enough to see what went on while scanning the log.  'Fix bug' IMO in
 the summary doesn't work at all because, although its accurate, that
 bug could literally be anything at all.

 Multi-package commits are going to be more of an issue of course..  I
 did one last night, fortunately I think I can get away with using
 mozilla packages in place of cat/pn since it is a very specific set
 of packages.  Perhaps for sweeping changes like that we can use the
 herdname or projectname or the category name (if its a particular
 category only)?



 The CATEGORY: prefix is already in the wiki. Interesting idea about
 projectname/herdname prefix.

 I've already seen someone (I think ulm) prefixing with [QA].

 I don't feel strong about this. IMO, if there is no useful prefix...
 just don't use any. The lack of prefix will make it obvious that this is
 a larger change. But project/herd specific prefixes could still make sense.

Mgorny has commited a fix to live portage

https://github.com/gentoo/portage/commit/46dafadff58da0220511f20480b73ad09f913430

I think it will be in the tree soon.

Re: [gentoo-dev] Summary line

[hasufell]

On 08/11/2015 04:28 PM, Ian Stakenvicius wrote:
 On 11/08/15 04:57 AM, Tobias Klausmann wrote:
 The more we stuff into the summary line, the harder it will be to 
 write meaningful summaries. And thus, people will write crappy ones
 or ignore the length limit. I recommend against any more 
 prescription over Add the the cat/pn if meaningful, don't use more
 than 75 characters.
 
 The cat/pn rule is tricky anyway: what if one commit touches 100 
 packages? Or should that be split into 100 commits for easier 
 partial rollback?
 
 Regards, Tobias
 
 
 
 The summary line limit is going to be a real issue, tbh.  I think it
 would probably be best to adopt the convention of putting a few
 choice, perhaps even canned, phrases in the summary line, and ensure
 any and all details (effectively what the summary line used to be for
 when it had practically no limit) within the commit message body instead
 .
 
 Stuff like 'cat/pn: version bumps', 'cat/pn: new features', 'cat/pn:
 adjusted dependencies' are generic (and short) enough yet descriptive
 enough to see what went on while scanning the log.  'Fix bug' IMO in
 the summary doesn't work at all because, although its accurate, that
 bug could literally be anything at all.
 
 Multi-package commits are going to be more of an issue of course..  I
 did one last night, fortunately I think I can get away with using
 mozilla packages in place of cat/pn since it is a very specific set
 of packages.  Perhaps for sweeping changes like that we can use the
 herdname or projectname or the category name (if its a particular
 category only)?
 
 
 

The CATEGORY: prefix is already in the wiki. Interesting idea about
projectname/herdname prefix.

I've already seen someone (I think ulm) prefixing with [QA].

I don't feel strong about this. IMO, if there is no useful prefix...
just don't use any. The lack of prefix will make it obvious that this is
a larger change. But project/herd specific prefixes could still make sense.

Re: [gentoo-dev] Summary line

[Ian Stakenvicius]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 11/08/15 10:35 AM, Kent Fredric wrote:
 On 12 August 2015 at 02:28, Ian Stakenvicius a...@gentoo.org
 wrote:
 Stuff like 'cat/pn: version bumps', 'cat/pn: new features',
 'cat/pn: adjusted dependencies' are generic (and short) enough
 yet descriptive enough to see what went on while scanning the
 log.
 
 I personally find those summaries a bit too terse.
 
 Mostly, because when I see A version is bumped I immediately
 expect to know which version the bump is to, but have to dig out
 the diff to find out.
 
 I would also prefer, where possible, to replace adjusted 
 dependencies to be more concise, like include dev-perl/Foo in 
 dependencies, ( though of course, apply some taste, listing more
 than 3 distinct new dependencies in the summary is execessive,
 treat them like hashtags on twitter, 1 is good, 2 is OK, 3 and
 you're starting to get crazy )
 

I agree, these are short and don't have nearly as much meaning as
they should -- if there's space, absolutely we should add more
meaning.  I think my point still stands though that the short
description should be more like these messages rather than fix
bug#someting when there's absolutely no indication of what the bug
is actually about.

So long as all of the details are in the main commit message body,
of course...

-BEGIN PGP SIGNATURE-
Version: GnuPG v2

iF4EAREIAAYFAlXKFFcACgkQAJxUfCtlWe0FRAEAgrL/FYmdYlA10JQyjkhrWPW6
Md6CjK5CCWQh35sz5U8A/Agp6d8HHSu69ZinmhE1VCw9D8TjJ3r5WtQYEo0X8Vhj
=WHfg
-END PGP SIGNATURE-