-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Juliano F. Ravasi wrote:
Brion Vibber wrote:
If you do point to external documentation instead of keeping the details in one place, put in a URL if possible to make it easy to jump right there.
From my personal experience, avoid putting URLs in commit messages. Commit messages are more or less set in stone after the commit, to change them you have to go through a few hiccups on most VCSs; while URLs are very dynamic, may change or became unavailable easily.
Good URLs are better than vague descriptions. During the period they continue to work, they remain directly clickable. After they break, you still have all the information needed --
https://bugzilla.wikimedia.org/show_bug.cgi?id=10931#c24
Gives us all this information:
* Bugzilla * of Wikimedia * bug number 10931 * comment number 24
That's every bit of information that was written out by hand, *plus* it's directly clickable.
I can't think of any situation in which I'd prefer that this commit message had the written-out, non-clickable form instead of the URL.
I would of course prefer the *actual comment* to be there, as I said.
Platonides wrote:
Are you suggesting easy changing of URLs?? You shall be condemned to sort the web for the rest of your days!! http://www.w3.org/Provider/Style/URI
If we were living in a perfect world, I agree that changing an URL would a bad, bad idea. But here, back to the real life, things are not that simple.
I have a friend that asked me to solve this very same problem on his company's subversion server. They moved their domain name from "hiscompanyname.com.br" to "histrademark.com", mainly because the new domain name was cheaper, shorter, easier to memorize and had a bigger commercial appeal. Unfortunately, their internal subversion server stored a lot of "intranet.hiscompanyname.com.br/tracker/..." URLs.
That's what redirects are for.
In Wikipedia we have the same problem. Just to cite one example, on the very early days, http://en.wikipedia.org/wiki/Java used to be the Wikipedia's article about the programming language. Then as time passed, it became a disambiguation page, and today it is an article about an island. The URL is the same, while its contents are completely different.
...and you have a handy disambiguation link right there to guide you to the correct place now. As the content evolves, proper stewardship means making sure it's still possible to reach things when they move, *and it has been done*.
- -- brion vibber (brion @ wikimedia.org)