New subject: links in commit messages: don't do it.

15 Oct 2013


      Dear Ron, dear coreboot folks,
Am Dienstag, den 15.10.2013, 10:52 -0700 schrieb ron minnich:
...
I see a commit went in with this text:
"... have tested on Ubuntu 13.04 with AMD Catalyst 13.4 Proprietary
Linux Display Driver[1].
[1].
http://support.amd.com/us/gpudownload/linux/Pages/radeon_linux.aspx"
...
OK, if you click on that link you find it contains very little useful
information: it's a web form with four fields. It doesn't actually
point to the driver and it's not clear on first looking at it just how
I *would* get that driver.
come on, it is obvious to go through each step and to give more details
in each step. But I agree that having a direct link to the file would
have been better.
...
And, in time, it will become another dead link in our growing pool of
dead links.
So what information was added by this link? None. The text was more
than sufficient.
If the text was sufficient to you, just ignore the reference and don’t
click on the link. It is that simple in my opinion. For me it is useful,
because I know how to better reproduce Siyuan’s setup. With the
reference I know he did not use the driver from the package repository,
I know where to get it from and do not have to search for that myself.
It saves precious time!
...
Please don't put links in commit messages. I would -2 this CL but it
already went in.
Giving -2 because of an URL in the commit message is unjustified in my
opinion as -2 blocks a commit from being merged even if other think it
should go in.
As seen from above, I strongly disagree with forbidding URLs in commit
messages.
Please start by noticing, that our current workflow violates that rule
already. In every commit we have a line »Reviewed-on:
http://review.coreboot.org/XXXX%C2%AB containing an URL!
Furthermore I see the following advantages.
1. Links made the WWW successful. The browser is used in our workflow.
People read commit in Gerrit, Gitweb and the Web archive. So adding
links adds to usability. We do not always think of the right keywords to
put into search machines to find a datasheet. We do not always have a
Git checkout to look up a referenced commit hash. (It would be easier
for me to have the Gerrit review URL in commit [1] for example. At least
the commit summary would be nice as it is common in the Linux kernel
too. I haven’t met someone yet which memorizes commit hashes.) Links
make your life easier.
2. Giving an URL to a Web page containing further information and
background knowledge to better understand a commit is always good. It
safes you time and acts also as a reference/backup for your explanation
and reasoning of a change. Especially in Free Software projects were a
lot of people work on stuff in their free time, URLs to datasheets or
other information help a great deal to quickly read up on things they
forgot or did not know yet. URLs to datasheets come to my mind. The
commit author has already found that information and great page. Why not
share it and save the reviewer time.
3. If the URL should become invalid, with high probability the commit is
also pretty old by then and not looked at that often. During review,
during which the most people are going to look at a commit, the URL is
valid.
Even if it became invalid, there are still ways to retrieve the content
using some Web archive, caches or finding the changed URL with the help
of the URL in the commit message.
The advantage and time saving is way greater by just clicking on an URL
and directly getting to the Web page than having to search for it
yourself and wasting five seconds to see that the URL is invalid. In the
second case you have to search for the information anyway spending much
more time than these five seconds. Nobody stops using URLs on Web pages
despite they might get invalid/outdated. Why should we?
Ron, sometimes I have the impression, you miss the perspective of us
(me) non-professionals not working full-time on coreboot. And in my
experience, I spent a lot of time with searching for information, which
a simple URL to a datasheet would have saved me.
As you are the project founder you can of course set rules about
development practices. But, as there are a lot of contributors and
reviewers, I would prefer a public discussion on the list before making
policy decisions. Furthermore, such decisions should be documented! Our
current development guidelines live in the Wiki [1] and reference the
Git Wiki page [2]. If a new policy is decided on, it should be
documented there.
It would be awesome, if you could change your opinion on that issue.
Thanks,
Paul
[1] http://review.coreboot.org/3967
[2] http://www.coreboot.org/Development_Guidelines#Creating_Patches
[3] http://www.coreboot.org/Git#Commit_messages

Re: [coreboot] links in commit messages: don't do it.