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
>
>

[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