Re: [gentoo-dev] 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 <dyokunev@××××××××.ru> 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.