Doc: encourage programmatic versions in URLs

[trevorparker]

Just a few documentation updates to help convey #4910 and the programmatic use of version numbers.

I could see benefit in having more creative examples to demonstrate using #{version} in other stanzas as well (i.e.: within the link stanza), but that is not addressed here. At the very least, this will nudge people in the right direction.

[rolandwalker]

Thanks. This is a constructive contribution, as it is encoding current practice. But I'd like to hold off on changing the docs for now.

We definitely should keep CONTRIBUTING.md as simple as possible, because that will be read by first-time contributors – upon whom this project is highly dependent.

As for changing the other docs, I'd still like to wait a bit more just to see how re-using the version number plays out. It's definitely worth trying, but still somewhat experimental. We haven't been doing it long enough to be sure it is a net benefit.

It definitely makes work easier for some of our maintainers, but we may hear from more people who have issues when they want to interop with Cask (#260 (comment), #5458).

[trevorparker]

Thank you for the thorough response. I didn't investigate too deeply into the progression of re-using the version number except that the number of PRs being tweaked to incorporate version number re-use seemed to be increasing.

I can appreciate wanting to keep CONTRIBUTING.md simple and the experimental nature of this change. Closing for now.