Linking versions

[Davinnah]

I'm a new user to Github. I'm trying to understand how to create the version compare links you have in the changelog. Is there a github guide section that would make it more clear?

Great guide by the way!! Thanks for all your effort.

[olivierlacan]

Hey that's a great idea! Do you already have version tags? If so just format the URL as such:

[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0

This assumes that you have both a v0.2.0 and v0.3.0 tag pushed to your origin remote (on GitHub).

[nbibler]

The simplest way I've found to create and maintain the compare links for GitHub can be seen in our faraday-detailed_logger gem.

Basically, Markdown allows you to create link references which you can define at the bottom of a file, using the double-bracket notation ([Link Content][Reference Name]). There's a shorthand though, if you leave the second bracket empty, it defaults to using the Link Content as the reference name. So, you can just:

## [2.0.0][] / 2016-07-08
….

[2.0.0]: https://github.com/envylabs/faraday-detailed_logger/compare/v1.1.0...v2.0.0

I generally have the reference links at the bottom run in chronological order, which means I can just jump to the bottom of the file to append a new link. It seems to be the most simple/efficient structure I've found so far.

[nbibler]

Also: for your first version, I generally link to the GitHub tree endpoint (since there's no previous tag to compare it to).

## [1.0.0][] / 2014-07-02

* Stable release.

[1.0.0]: https://github.com/envylabs/faraday-detailed_logger/tree/v1.0.0

[olivierlacan]

You don't even need the extra brackets:

## [1.0.0] / 2014-07-02

* Stable release.

[1.0.0]: https://github.com/envylabs/faraday-detailed_logger/tree/v1.0.0

Closing since this is part of the guidelines.