-----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)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (Darwin)
Comment: Using GnuPG with Mozilla -
http://enigmail.mozdev.org
iEYEARECAAYFAkgDjO0ACgkQwRnhpk1wk44oHACgyvJM/wCisMRAGmwe7eS9oWYj
8C0An2GhPwWODdFkOrt20Ghy5U2SgUzC
=zciw
-----END PGP SIGNATURE-----