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