Re: [gentoo-dev] Summary line
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.
Re: [gentoo-dev] Summary line (was: Re: Referencing bug reports in git)
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? -- Rich
Re: [gentoo-dev] Summary line (was: Re: Referencing bug reports in git)
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
-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 > 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-
Re: [gentoo-dev] Summary line
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
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 (was: Re: Referencing bug reports in git)
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. 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
[gentoo-dev] Summary line (was: Re: Referencing bug reports in git)
-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-
