Referencing bug reports in git (WAS: Re: [gentoo-commits] repo/gentoo:master commit in: sci-libs/opencascade/)

classic Classic list List threaded Threaded
82 messages Options
12345
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Gordon Pettey
On Mon, Aug 10, 2015 at 7:25 AM, Duncan <[hidden email]> wrote:
** summary bug number standardized to GB#xxxxxx or #xxxxxx or similar,
short enough for summary, easily identified. GB# would be distinctly
gentoo and could be expanded to KDEB#, GNB# (gnome), FDOB#, etc, for

If you're going to prepend the project, just spell it out. Don't invent new acronyms and abbreviations. Don't add a B suffix to everything. If it's the same everywhere, then it is meaningless, and just confuses things. I know what KDE is, but I'd have to go Google for what KDEB is (Is that KDE B? K Debian?), and hope Google indexed the above email from gmane or something.

Don't prefix bugs with #. 1. It doesn't apply to every system: Random Project using Jira is going to have bugs like RP-123. You'd have to insert it in the middle of the identifier like RP-#123. 2. It is a relatively useless prefix at best: In the bug tracker UI, you search for 123, not #123. At worst, it makes the identifier invalid (as in the Jira example).
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Ryan Hill
In reply to this post by Duncan-42
On Mon, 10 Aug 2015 12:25:58 +0000 (UTC)
Duncan <[hidden email]> wrote:

> What about:
>
> * bug number in summary strongly recommended
> ** summary bug number standardized to GB#xxxxxx or #xxxxxx or similar,
> short enough for summary, easily identified. GB# would be distinctly
> gentoo and could be expanded to KDEB#, GNB# (gnome), FDOB#, etc, for
> projects where users likely to want to see the bug likely know what it is.
> ** summary lists gentoo bug if any, upstream only if no gentoo bug.
>
> * bug URL in description required.
> ** standardized to Gentoo-Bug: .......
> ** gives people wanting something to click a way to do so
> ** U in URL is universal, unambiguously identifies reference for those
> unfamiliar with summary shorthand.
> ** Multiple allowed, for multiple gentoo bugs or to identify upstream
> bugs (using FDO-Bug: or similar) as well.
>
> That seems a reasonable compromise, given people pulling both ways
> in-thread.
Making the bug number in the summary manditory or strongly encouraged leads to
wonderful commit messages like:

---
cat-pkg: Fix bug #504321.

Gentoo-Bug: 504321
---

I would like to see this be more common:

---
cat-pkg: Make the thingy work again.

Gentoo-Bug: https://bugs.gentoo.org/504321 or 504321 Idon'tcarewhich
----

If we're limiting the summary to 1 line, 70-75 chars, manditory cat/package
and bug number there's not a lot of room to summarize in.


--
Ryan Hill                        psn: dirtyepic_sk
   gcc-porting/toolchain/wxwidgets @ gentoo.org

47C3 6D62 4864 0E49 8E9E  7F92 ED38 BD49 957A 8463

attachment0 (486 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git (WAS: Re: [gentoo-commits] repo/gentoo:master commit in: sci-libs/opencascade/)

Ryan Hill
In reply to this post by Andrew Savchenko
On Mon, 10 Aug 2015 23:43:29 +0300
Andrew Savchenko <[hidden email]> wrote:

> On Mon, 10 Aug 2015 15:11:02 +0200 Michał Górny wrote:
> > > > > 2. Bug number can be easily typed, URL has to be copied or
> > > > > generated by some tool.
> > > >
> > > > So, please remind me, how many times the 'easy typing' got the bug
> > > > number wrong? This is not a real argument, just another of Gentoo's
> > > > 'I'm too lazy to do things right'.
> > >
> > > URLs are longer, so probability of error during typing increases
> > > compared to raw numbers.
> >
> > Not really. You are closer to the threshold when you are too lazy to
> > type it and you just copy-paste it.
>
> Copy and pasting requires more time than typing 6 digits.
>  
> > > > > 3. Too many text, hard to read. Some bugs may refer to a dozen of
> > > > > URLs.
> > > >
> > > > And how is a dozen numbers better?
> > >
> > > Less text, more readable.
> >
> > How is:
> >
> >   Bug: 123451, 453445, 344334, 343444
> >
> > more readable than:
> >
> >   Bug: https://bugs.gentoo.org/123451
> >   Bug: https://bugs.gentoo.org/453445
> >   Bug: https://bugs.gentoo.org/344334
> >   Bug: https://bugs.gentoo.org/343444
> >
> > Readability is a matter of formatting, not contents.
>
> 1. One line and 35 chars are certainly more readable than four lines
> and 140 chars.
It isn't.  There's a reason why lists of things are generally written top to
bottom.  I found the second form to be much more readable.  In fact I was
generally against the URIs until I saw this.

> 2. Strings are read from left to right (at least in English), thus
> having most important information last on the line is not
> convenient.

Maybe if you were reading the whole line, but you're not.  You have built-in
pattern recognition.  Try it out.

> 3. A lot of duplicated and useless information consumes time and
> space, irritating people.

Arg, that is so irritating how I have easily-clickable machine-parsable links in
my git log. Look at all the space we could have saved!  How much time have I
wasted reading every character?!  Sorry kids, can't play, daddy's busy reading
commit logs.

No matter what we decide three months from now we won't remember arguing about
it.  So let's save some time an irritability now and pick something.



--
Ryan Hill                        psn: dirtyepic_sk
   gcc-porting/toolchain/wxwidgets @ gentoo.org

47C3 6D62 4864 0E49 8E9E  7F92 ED38 BD49 957A 8463

attachment0 (486 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Duncan-42
In reply to this post by Gordon Pettey
Gordon Pettey posted on Mon, 10 Aug 2015 17:57:56 -0500 as excerpted:

> On Mon, Aug 10, 2015 at 7:25 AM, Duncan <[hidden email]> wrote:
>
>> ** summary bug number standardized to GB#xxxxxx or #xxxxxx or similar,
>> short enough for summary, easily identified. GB# would be distinctly
>> gentoo and could be expanded to KDEB#, GNB# (gnome), FDOB#, etc, for
>>
>>
> If you're going to prepend the project, just spell it out.

My thought is that this is the one-line summary, generally limited to 75
chars, including category/package.  Spelling it out thus takes precious
character-space that can better be used to describe the problem in words.

> Don't add a B suffix to everything. If it's the same everywhere, then
> it is meaningless, and just confuses things.

Very good point, particularly in light of the above -- that's another
character-slot from 75 that can't be used for other things.

> Don't prefix bugs with #. 1. It doesn't apply to every system: Random
> Project using Jira is going to have bugs like RP-123. You'd have to
> insert it in the middle of the identifier like RP-#123. 2. It is a
> relatively useless prefix at best: In the bug tracker UI, you search for
> 123, not #123. At worst, it makes the identifier invalid (as in the Jira
> example).

Once again, very good point.  Thanks. =:^)

--
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman


Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Duncan-42
In reply to this post by Ryan Hill
Ryan Hill posted on Mon, 10 Aug 2015 18:17:30 -0600 as excerpted:

> On Mon, 10 Aug 2015 12:25:58 +0000 (UTC)
> Duncan <[hidden email]> wrote:
>> What about:
>>
>> * bug number in summary strongly recommended
>
> Making the bug number in the summary manditory or strongly encouraged
> leads to wonderful commit messages like:
>
> ---
> cat-pkg: Fix bug #504321.

Ideally, it'd be something a bit more informative (here taking Gordon's
points about the previously suggested B#):

cat-egory/semi-long-package-name: fix amd64-fbsd build error G-504321

> I would like to see this be more common:
>
> ---
> cat-pkg: Make the thingy work again
>
> Gentoo-Bug: https://bugs.gentoo.org/504321 *(or 504321 Idon'tcarewhich)
> ----
>
> If we're limiting the summary to 1 line, 70-75 chars, manditory
> cat/package and bug number there's not a lot of room to summarize in.

Note that a bug number would fit in your above summary very easily,
omitting nothing, as it's only ~35/75 length.

Even with my somewhat longer cat/pkg example with the longest arch-
keyword I could quickly find, there's still room to indicate at minimum
build vs runtime error, with the gentoo bug number reference for anyone
who might find it interesting enough to look further than the one-line.  
People can then either select and klipper-popup (adding my usual trigger
method to the others people have mentioned), or read the longer
description for the full bug URL to click, if they prefer.

--
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman


Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git (WAS: Re: [gentoo-commits] repo/gentoo:master commit in: sci-libs/opencascade/)

Dmitry Yu Okunev
In reply to this post by Michał Górny-5
Hello.

I'm not a gentoo-dev, so sorry if I shouldn't express my thoughts with
my lame English here. Please tell me if it's so.

On 08/11/2015 12:06 AM, Michał Górny wrote:

>>>>>> 3. Too many text, hard to read. Some bugs may refer to a dozen of
>>>>>> URLs.
>>>>>
>>>>> And how is a dozen numbers better?
>>>>
>>>> Less text, more readable.
>>>
>>> How is:
>>>
>>>   Bug: 123451, 453445, 344334, 343444
>>>
>>> more readable than:
>>>
>>>   Bug: https://bugs.gentoo.org/123451
>>>   Bug: https://bugs.gentoo.org/453445
>>>   Bug: https://bugs.gentoo.org/344334
>>>   Bug: https://bugs.gentoo.org/343444
>>>
>>> Readability is a matter of formatting, not contents.
>>
>> 1. One line and 35 chars are certainly more readable than four lines
>> and 140 chars.
>
> Character counts are completely irrelevant to readability. Visual space
> is. And in this case, exhibit A (also known as wall of digits) is more
> likely to get people confused.
I think it's just individual preference. No sense to argue this. Just
everybody should consider that there exists another position on this
question.

However I want to add an other argument:

1a. It's easier to parse the "Bug:" header is there only bug IDs
(without URLs).

And is there any guarantee that URL format won't be changed in future
(that everybody won't be have to rewrite their parsers). I mean not
"near future", but "any long future".

>> 2. Strings are read from left to right (at least in English), thus
>> having most important information last on the line is not
>> convenient.
>
> This is not literature. Keys usually precede values, and namespaces
> precede namespaced identifiers.

A commit-comment is not a source code. It's an ordinary text (like
"literature").

>> 3. A lot of duplicated and useless information consumes time and
>> space, irritating people.
>
> Well, maybe I'm very special then because I can *instantly* notice that
> the four quoted lines are almost identical and differ only by bug
> numbers.

Yes. But as for me this duplicated text adds a lot of garbage to the
total text of a comment. It's harder to fast look over it. You were
right — "Visual space" does matter.

And Andrew said "useless information" — I agree.

>> 4. Think about people using special accessibility devices like
>> speech-to-text engine or Braille terminal. It will be pain for them
>> to read all this notorious URLs. And we have at least one developer
>> relying upon such devices.
>
> And that's the first valid argument. Though I would doubt that
> accessibility software handles random numbers better than URLs. Unless
> you consider retyping one of the six numbers you just heard easier than
> triggering some kind of URL activation feature.

I remember that William Hubbs asked me to remove one very simple
ASCII-arted scheme (that explains how the code works) from a patch,
because it's very inconvenient to listen that stuff using speech-to-text
engines. May be somebody should just ask him for his opinion on this
question? I think it's more convenient to listen pure bug IDs rather
than a lot of full URLs.

>>>> What is a corner case? Why not defining "clicking on the link in
>>>> the git log" as a corner case?
>>>
>>> As far as I'm aware, URLs are supported much more widely than
>>> Gentoo-specific bug numbers. They are uniform and unique by definition.
>>> The tools using bug numbers can be easily expanded to extract them from
>>> URLs. I don't really see forking cgit to support Gentoo bug numbers, or
>>> asking github to provide special rules for our commits.
>>
>> We should not adjust our ecosystem for closed and proprietary
>> solutions like github.
>
> URLs are not github invention. Localized bug numbers are local Gentoo
> non-sense. So should we adjust it to ignore the rest of the world and
> expect everyone to create custom hackery just to be able to see a bug
> report?
You can use header "Gentoo-Bug:" (instead of "Bug:") and explain in
documentation ways to parse that.

--
Best regards, Dmitry.


signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git (WAS: Re: [gentoo-commits] repo/gentoo:master commit in: sci-libs/opencascade/)

Michał Górny-5
Dnia 2015-08-11, o godz. 09:56:55
Dmitry Yu Okunev <[hidden email]> napisał(a):

> Hello.
>
> I'm not a gentoo-dev, so sorry if I shouldn't express my thoughts with
> my lame English here. Please tell me if it's so.
>
> On 08/11/2015 12:06 AM, Michał Górny wrote:
> >>>>>> 3. Too many text, hard to read. Some bugs may refer to a dozen of
> >>>>>> URLs.
> >>>>>
> >>>>> And how is a dozen numbers better?
> >>>>
> >>>> Less text, more readable.
> >>>
> >>> How is:
> >>>
> >>>   Bug: 123451, 453445, 344334, 343444
> >>>
> >>> more readable than:
> >>>
> >>>   Bug: https://bugs.gentoo.org/123451
> >>>   Bug: https://bugs.gentoo.org/453445
> >>>   Bug: https://bugs.gentoo.org/344334
> >>>   Bug: https://bugs.gentoo.org/343444
> >>>
> >>> Readability is a matter of formatting, not contents.
> >>
> >> 1. One line and 35 chars are certainly more readable than four lines
> >> and 140 chars.
> >
> > Character counts are completely irrelevant to readability. Visual space
> > is. And in this case, exhibit A (also known as wall of digits) is more
> > likely to get people confused.
>
> I think it's just individual preference. No sense to argue this. Just
> everybody should consider that there exists another position on this
> question.
>
> However I want to add an other argument:
>
> 1a. It's easier to parse the "Bug:" header is there only bug IDs
> (without URLs).
What if there are different bug trackers involved? We sometimes note
upstream bugs, other distro bugs, pull requests...

> And is there any guarantee that URL format won't be changed in future
> (that everybody won't be have to rewrite their parsers). I mean not
> "near future", but "any long future".

I doubt it can change *without* changing the bug tracker software.
And then, old IDs will no longer be relevant. In fact, since the URLs
are Bugzilla-specific it will allow us to ensure better compatibility
if we start numbering bugs from 1 again.

There's URL and there's URI. Even if URL is no longer valid, it will
still be a valid URI. It will still allow us to uniquely identify
the bug report.

> >> 2. Strings are read from left to right (at least in English), thus
> >> having most important information last on the line is not
> >> convenient.
> >
> > This is not literature. Keys usually precede values, and namespaces
> > precede namespaced identifiers.
>
> A commit-comment is not a source code. It's an ordinary text (like
> "literature").

Literature is a long continuous text which you read left-to-right,
and usually without going back. This is short text which you read
randomly, possibly going back and forth, and scanning for specific
details.

> >>> As far as I'm aware, URLs are supported much more widely than
> >>> Gentoo-specific bug numbers. They are uniform and unique by definition.
> >>> The tools using bug numbers can be easily expanded to extract them from
> >>> URLs. I don't really see forking cgit to support Gentoo bug numbers, or
> >>> asking github to provide special rules for our commits.
> >>
> >> We should not adjust our ecosystem for closed and proprietary
> >> solutions like github.
> >
> > URLs are not github invention. Localized bug numbers are local Gentoo
> > non-sense. So should we adjust it to ignore the rest of the world and
> > expect everyone to create custom hackery just to be able to see a bug
> > report?
>
> You can use header "Gentoo-Bug:" (instead of "Bug:") and explain in
> documentation ways to parse that.
So you're suggesting it's better to invent a custom format and tell
people how to handle it, rather than use a commonly-supported format?

--
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>

attachment0 (968 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git (WAS: Re: [gentoo-commits] repo/gentoo:master commit in: sci-libs/opencascade/)

Dmitry Yu Okunev


On 08/11/2015 10:12 AM, Michał Górny wrote:

> Dnia 2015-08-11, o godz. 09:56:55
> Dmitry Yu Okunev <[hidden email]> napisał(a):
>> On 08/11/2015 12:06 AM, Michał Górny wrote:
>>>>>>>> 3. Too many text, hard to read. Some bugs may refer to a dozen of
>>>>>>>> URLs.
>>>>>>>
>>>>>>> And how is a dozen numbers better?
>>>>>>
>>>>>> Less text, more readable.
>>>>>
>>>>> How is:
>>>>>
>>>>>   Bug: 123451, 453445, 344334, 343444
>>>>>
>>>>> more readable than:
>>>>>
>>>>>   Bug: https://bugs.gentoo.org/123451
>>>>>   Bug: https://bugs.gentoo.org/453445
>>>>>   Bug: https://bugs.gentoo.org/344334
>>>>>   Bug: https://bugs.gentoo.org/343444
>>>>>
>>>>> Readability is a matter of formatting, not contents.
>>>>
>>>> 1. One line and 35 chars are certainly more readable than four lines
>>>> and 140 chars.
>>>
>>> Character counts are completely irrelevant to readability. Visual space
>>> is. And in this case, exhibit A (also known as wall of digits) is more
>>> likely to get people confused.
>>
>> I think it's just individual preference. No sense to argue this. Just
>> everybody should consider that there exists another position on this
>> question.
>>
>> However I want to add an other argument:
>>
>> 1a. It's easier to parse the "Bug:" header is there only bug IDs
>> (without URLs).
>
> What if there are different bug trackers involved? We sometimes note
> upstream bugs, other distro bugs, pull requests...
For example Gentoo may use "Gentoo-Bug:"/"Bug-Gentoo:" as I mentioned.
Debian uses "Bug-Debian:" for Debian ITS references and "Bug:" for
upstream bugreport references in their patches (debian/patches/*), IIRC.

>> And is there any guarantee that URL format won't be changed in future
>> (that everybody won't be have to rewrite their parsers). I mean not
>> "near future", but "any long future".
>
> I doubt it can change *without* changing the bug tracker software.
> And then, old IDs will no longer be relevant.

Why? Just migrate with saved IDs.

> In fact, since the URLs
> are Bugzilla-specific it will allow us to ensure better compatibility
> if we start numbering bugs from 1 again.

IMHO, it's a really bad idea to do not migrate previous data to the new ITS.

> There's URL and there's URI. Even if URL is no longer valid, it will
> still be a valid URI. It will still allow us to uniquely identify
> the bug report.

Only if you will use Bugzilla or some workarounds to imitate Bugzilla.
It's a lock-in.

>>>> 2. Strings are read from left to right (at least in English), thus
>>>> having most important information last on the line is not
>>>> convenient.
>>>
>>> This is not literature. Keys usually precede values, and namespaces
>>> precede namespaced identifiers.
>>
>> A commit-comment is not a source code. It's an ordinary text (like
>> "literature").
>
> Literature is a long continuous text which you read left-to-right,
> and usually without going back. This is short text which you read
> randomly, possibly going back and forth, and scanning for specific
> details.
Well, ok. But personally I have a habit to read such text left-to-right.
It requires split seconds to recognize this lines similarity but it
requires.

Anyway as I said, I will see much more garbage while looking on the
whole text if you will use URLs instead of pure IDs.

>>>>> As far as I'm aware, URLs are supported much more widely than
>>>>> Gentoo-specific bug numbers. They are uniform and unique by definition.
>>>>> The tools using bug numbers can be easily expanded to extract them from
>>>>> URLs. I don't really see forking cgit to support Gentoo bug numbers, or
>>>>> asking github to provide special rules for our commits.
>>>>
>>>> We should not adjust our ecosystem for closed and proprietary
>>>> solutions like github.
>>>
>>> URLs are not github invention. Localized bug numbers are local Gentoo
>>> non-sense. So should we adjust it to ignore the rest of the world and
>>> expect everyone to create custom hackery just to be able to see a bug
>>> report?
>>
>> You can use header "Gentoo-Bug:" (instead of "Bug:") and explain in
>> documentation ways to parse that.
>
> So you're suggesting it's better to invent a custom format and tell
> people how to handle it, rather than use a commonly-supported format?
What you mean with the "custom format"? I suggest to use comment as a
comment, but not as a documentation about "How to reach Gentoo ITS" in
every comment.

I can agree with another argument:
There should be a possibility to define an upstream bug which format in
turn can be simply unified only by URLs. And it may became harder to
read when neighboring headlines are formatted different ways (one header
— pure IDs, another one — URLs). But _IMHO_, it doesn't outweigh
disadvantages of this approach (with URLs for reference on Gentoo bug).

--
Best regards, Dmitry.


signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Tobias Klausmann-4
In reply to this post by Duncan-42
Hi!

On Tue, 11 Aug 2015, Duncan wrote:

> Ryan Hill posted on Mon, 10 Aug 2015 18:17:30 -0600 as excerpted:
>
> > On Mon, 10 Aug 2015 12:25:58 +0000 (UTC)
> > Duncan <[hidden email]> wrote:
> >> What about:
> >>
> >> * bug number in summary strongly recommended
> >
> > Making the bug number in the summary manditory or strongly encouraged
> > leads to wonderful commit messages like:
> >
> > ---
> > cat-pkg: Fix bug #504321.
>
> Ideally, it'd be something a bit more informative (here taking Gordon's
> points about the previously suggested B#):
>
> cat-egory/semi-long-package-name: fix amd64-fbsd build error G-504321
>
> > I would like to see this be more common:
> >
> > ---
> > cat-pkg: Make the thingy work again
> >
> > Gentoo-Bug: https://bugs.gentoo.org/504321 *(or 504321 Idon'tcarewhich)
> > ----
> >
> > If we're limiting the summary to 1 line, 70-75 chars, manditory
> > cat/package and bug number there's not a lot of room to summarize in.
>
> Note that a bug number would fit in your above summary very easily,
> omitting nothing, as it's only ~35/75 length.
>
> Even with my somewhat longer cat/pkg example with the longest arch-
> keyword I could quickly find, there's still room to indicate at minimum
> build vs runtime error, with the gentoo bug number reference for anyone
> who might find it interesting enough to look further than the one-line.  
> People can then either select and klipper-popup (adding my usual trigger
> method to the others people have mentioned), or read the longer
> description for the full bug URL to click, if they prefer.

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

--
Sent from aboard the Culture ship
        Fine Till You Came Along

Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Kent Fredric
On 11 August 2015 at 20:57, Tobias Klausmann <[hidden email]> wrote:
>
> 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?


I think you've misread "The rule"

https://wiki.gentoo.org/wiki/Gentoo_git_workflow#Commit_Message_Format

Emphasis added:

>> commits that affect **primarily** a particular subsystem should prepend the >> following code to the first line of the commit message:

>> **if the change affects multiple directories**, but is mostly related to a particular subsystem, then prepend the subsystem which best reflects the intention (e.g. you add a new license, but also modify profiles/license_group


--
Kent

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

Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

Rich Freeman
On Tue, Aug 11, 2015 at 5:12 AM, Kent Fredric <[hidden email]> wrote:
> On 11 August 2015 at 20:57, Tobias Klausmann <[hidden email]> wrote:
>>
>> 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?
>
>>> **if the change affects multiple directories**, but is mostly related to a particular subsystem, then prepend the subsystem which best reflects the intention (e.g. you add a new license, but also modify profiles/license_group

++
Go read the proposal.  This email chain simplifies it but people have
already thought of most of those corner cases already.

However, I do want to touch on this bit from the previous email: "Or
should that be split into 100 commits for easier partial rollback?"

Each commit should be one logical change.  If you stabilize 100
separate packages in an afternoon, there should be 100 commits.  If
you stabilize kde-5.0 there probably should be one commit that touches
100 packages.  Likewise if you rename a package and fix 100 references
to it in other packages, that should probably also be a single commit
(but I'd separate renaming the package from any other changes to the
content of the package).

That is actually one of the advantages of git.  You can stabilize
kde-5 and a user doing an rsync will either get kde 4.x or the full
kde 5, and nothing in-between.

But, one commit in the final tree should still remain one logical change.

--
Rich

Reply | Threaded
Open this post in threaded view
|

Re: Referencing bug reports in git

hasufell
On 08/11/2015 01:49 PM, Rich Freeman wrote:

> On Tue, Aug 11, 2015 at 5:12 AM, Kent Fredric <[hidden email]> wrote:
>> On 11 August 2015 at 20:57, Tobias Klausmann <[hidden email]> wrote:
>>>
>>> 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?
>>
>>>> **if the change affects multiple directories**, but is mostly related to a particular subsystem, then prepend the subsystem which best reflects the intention (e.g. you add a new license, but also modify profiles/license_group
>
> ++
> Go read the proposal.  This email chain simplifies it but people have
> already thought of most of those corner cases already.
>
> However, I do want to touch on this bit from the previous email: "Or
> should that be split into 100 commits for easier partial rollback?"
>
> Each commit should be one logical change.  If you stabilize 100
> separate packages in an afternoon, there should be 100 commits.  If
> you stabilize kde-5.0 there probably should be one commit that touches
> 100 packages.  Likewise if you rename a package and fix 100 references
> to it in other packages, that should probably also be a single commit
> (but I'd separate renaming the package from any other changes to the
> content of the package).
>
> That is actually one of the advantages of git.  You can stabilize
> kde-5 and a user doing an rsync will either get kde 4.x or the full
> kde 5, and nothing in-between.
>
> But, one commit in the final tree should still remain one logical change.
>

Right.

In addition, we just took the freedom to add the clause "all commits
must be repoman-valid":
https://wiki.gentoo.org/index.php?title=Gentoo_git_workflow&diff=352978&oldid=352858

That will be necessary too for the CI work mgorny is doing and will also
make bisecting and cherry-picking easier.

That is: if splitting up a commit into several makes repoman fail on
some of them, it probably should be one commit instead (or you have to
reconsider the order you commit stuff in... e.g. first add the license
and then the package).


But we are drifting OT again.

Reply | Threaded
Open this post in threaded view
|

Summary line (was: Re: Referencing bug reports in git)

Ian Stakenvicius-2
In reply to this post by Tobias Klausmann-4
-----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-----

Reply | Threaded
Open this post in threaded view
|

Re: Summary line (was: Re: Referencing bug reports in git)

Kent Fredric
On 12 August 2015 at 02:28, Ian Stakenvicius <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Summary line

hasufell
In reply to this post by Ian Stakenvicius-2
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.

Reply | Threaded
Open this post in threaded view
|

Re: Summary line

Mikle Kolyada-2


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.

Reply | Threaded
Open this post in threaded view
|

Re: Summary line

Ian Stakenvicius-2
In reply to this post by Kent Fredric
-----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 <[hidden email]>
> 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-----

Reply | Threaded
Open this post in threaded view
|

Bisecting Was: Referencing bug reports in git

Duncan-42
In reply to this post by hasufell
hasufell posted on Tue, 11 Aug 2015 13:58:20 +0200 as excerpted:

> In addition, we just took the freedom to add the clause "all commits
> must be repoman-valid":
> https://wiki.gentoo.org/index.php?
title=Gentoo_git_workflow&diff=352978&oldid=352858
>
> That will be necessary too for the CI work mgorny is doing and will also
> make bisecting and cherry-picking easier.

The mention of bisect got me thinking... I'm not exactly sure I'm wording
this right, but hopefully the question is clear enough...

What are the practical implications of and reasons for doing a bisect, on
a package-tree repo, where it's typically the out-of-tree package sources
where most functionality-bisection would happen, and in-tree commits tend
to result in atomic package updates, or at least atomic USE flag, etc,
changes on a package?

The typical reason for a bisect is to find the commit where a bug
originated, but that's upstream package/project bisects.  I don't quite
see how that maps to distro package tree repo bisects, as it seems to me
there's nothing really to bisect -- problems should be with specific
package versions or with USE flag or similar changes within an ebuild/
eclass, and it seems to me that's known along with awareness of the
problem in the first place, leaving no reason to bisect to find the
problem.

Tho arguably eclass change issues are an exception, and bisectable in the
usual sense for the usual purpose.  Actually, that could make
troubleshooting eclass updates MUCH simpler than it was before.  Luckily,
at least I as a user didn't end up with too many direct eclass issues to
troubleshoot.

Tho I can definitely think of a non-traditional use for bisect.  While I
update my workstation more or less weekly, I updated my 32-bit
netbook[1]  far less frequently, every year or two.  It occurs to me that
using git bisect to automate working out the resulting update issues
might be far easier than some of the manual tricks and workaround I used
to end up doing, to finally get an updated to current, working system
once again.  Bisect start, immediately declare bisect bad, inner looping
until I got to about a three-month update, update to it, bisect reset,
outer-looping on the bisect to another 3-4 month update... until I was
caught up.  Of course one can't go back past our current switch to git,
but in five years, one could in theory pull the old laptop out that was
last updated yesterday, and roll back gentoo's now five-years-future tree
four years and nine months, and start the update process, ultimately
bringing it upto date without starting with a new stage tarball install,
as would have been the only really feasible pre-git alternative for a
five-year-outdated system.  Not that a new stage tarball wouldn't be
faster after five years in any case, but at least the incremental update-
in-place should now be possible.

---
[1] 32-bit netbook: Now gone and not yet replaced, but I intend to get
another, tho amd64 this time so I can mostly build once for both, one for
three if I setup an amd64-based router as I intend to as well, and
hopefully avoid the year-plus update period issue as I can just binpkg-
update after the first one.

--
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman


Reply | Threaded
Open this post in threaded view
|

Re: Bisecting Was: Referencing bug reports in git

Jason Zaman-2
On Wed, Aug 12, 2015 at 07:20:54AM +0000, Duncan wrote:

> hasufell posted on Tue, 11 Aug 2015 13:58:20 +0200 as excerpted:
>
> > In addition, we just took the freedom to add the clause "all commits
> > must be repoman-valid":
> > https://wiki.gentoo.org/index.php?
> title=Gentoo_git_workflow&diff=352978&oldid=352858
> >
> > That will be necessary too for the CI work mgorny is doing and will also
> > make bisecting and cherry-picking easier.
>
> The mention of bisect got me thinking... I'm not exactly sure I'm wording
> this right, but hopefully the question is clear enough...
>
> What are the practical implications of and reasons for doing a bisect, on
> a package-tree repo, where it's typically the out-of-tree package sources
> where most functionality-bisection would happen, and in-tree commits tend
> to result in atomic package updates, or at least atomic USE flag, etc,
> changes on a package?
>
> The typical reason for a bisect is to find the commit where a bug
> originated, but that's upstream package/project bisects.  I don't quite
> see how that maps to distro package tree repo bisects, as it seems to me
> there's nothing really to bisect -- problems should be with specific
> package versions or with USE flag or similar changes within an ebuild/
> eclass, and it seems to me that's known along with awareness of the
> problem in the first place, leaving no reason to bisect to find the
> problem.
>
> Tho arguably eclass change issues are an exception, and bisectable in the
> usual sense for the usual purpose.  Actually, that could make
> troubleshooting eclass updates MUCH simpler than it was before.  Luckily,
> at least I as a user didn't end up with too many direct eclass issues to
> troubleshoot.

I agree that bisecting would typically not happen that often because
usually you'd just emerge =cat/pkg-1.2.3 but there are times when
updates are done without a revbump that might have broken something so
it could be useful. Also eclasses would definitely be useful. There are
a few useful cases when it might make things easier but probably rare,
tho its good to have the tool available in case.

> Tho I can definitely think of a non-traditional use for bisect.  While I
> update my workstation more or less weekly, I updated my 32-bit
> netbook[1]  far less frequently, every year or two.  It occurs to me that
> using git bisect to automate working out the resulting update issues
> might be far easier than some of the manual tricks and workaround I used
> to end up doing, to finally get an updated to current, working system
> once again.  Bisect start, immediately declare bisect bad, inner looping
> until I got to about a three-month update, update to it, bisect reset,
> outer-looping on the bisect to another 3-4 month update... until I was
> caught up.  Of course one can't go back past our current switch to git,
> but in five years, one could in theory pull the old laptop out that was
> last updated yesterday, and roll back gentoo's now five-years-future tree
> four years and nine months, and start the update process, ultimately
> bringing it upto date without starting with a new stage tarball install,
> as would have been the only really feasible pre-git alternative for a
> five-year-outdated system.  Not that a new stage tarball wouldn't be
> faster after five years in any case, but at least the incremental update-
> in-place should now be possible.

I like the idea, but its probably easier to just
git checkout $(git rev-list -n 1 --before="2015-12-01 12:00" master)
and then you just change the date a month at a time or something

-- Jason

> ---
> [1] 32-bit netbook: Now gone and not yet replaced, but I intend to get
> another, tho amd64 this time so I can mostly build once for both, one for
> three if I setup an amd64-based router as I intend to as well, and
> hopefully avoid the year-plus update period issue as I can just binpkg-
> update after the first one.
>
> --
> Duncan - List replies preferred.   No HTML msgs.
> "Every nonfree program has a lord, a master --
> and if you use the program, he is your master."  Richard Stallman
>
>

Reply | Threaded
Open this post in threaded view
|

Re: Bisecting Was: Referencing bug reports in git

Duncan-42
Jason Zaman posted on Wed, 12 Aug 2015 15:38:01 +0800 as excerpted:

>> Tho I can definitely think of a non-traditional use for bisect.  
>> [When a system hasn't been updated in over a year, bisect the update.]
>
> I like the idea, but its probably easier to just git checkout $(git
> rev-list -n 1 --before="2015-12-01 12:00" master) and then you just
> change the date a month at a time or something

You're correct, and I did think about that, but...

The nice thing with bisect at least in something like the kernel where
most of the direct main-tree changes are merges, is that it'll stay at
the higher merge level as long as possible, drilling down to individual
commits only after bisects to an individual merge.

Again, however, I'm not entirely sure how that translates to gentoo's
rebase-and-fast-forward recommendation, with fewer merges.  But at the
3-4 month level, if it avoids landing in the middle of a kde or gnome
update, that'd be very useful.

It could well be that with gentoo's merges-discouraged workflow, the
effect would be the same either way, in which case, you're correct, your
suggestion would be easier.

But it's still a creative use of bisect I hadn't thought of before, even
if bisect isn't the most efficient method to that end. Which means I know
a bit more about bisect than I did.  =:^)

--
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman


12345