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

[Dmitry Yu Okunev]

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.