add a CHANGELOG.html file that redirects to the actual changelog

[tilo]

Re issue #965

I didn't realize that you already have awesome change documentation - just not in the location that has become standard for Ruby gems.

This small change will make your existing changelog more discoverable -- both from RubyGems.org, as well as when someone browses your project.

Hope this helps

cheers

[nvasilevski]

This feels a little custom to be honest. GitHub releases is a very commonly used feature, what if we instead teach rubygems to point to github releases if gem has its source listed on github. This way many more gems can benefit while still allowing gems to have custom changelogs

Actually, we don't even need to change anything in rubygems. Rails for example despite of having CHANGELOG file still points to a specific tag which must be much convenient for the reader https://github.com/rails/rails/blob/bab4aa7cb25112846e04cea907361a1de0f126ef/rails.gemspec#L25

So perhaps making changelog_uri pointing to a specific tag or a release would be a better option?

[etiennebarrie]

Oh yes Rubocop does that, it's pretty nice: https://github.com/rubocop/rubocop/blob/dc50e8034183646f05e7009e917a452ec1f7ba7e/rubocop.gemspec#L27

Yeah we don't need the html file, it doesn't really redirect in the first place (at least on GitHub), but having every gem version point to the release sounds useful.

[tilo]

@nvasilevski the majority of Ruby gems does this, because this is the recommended process:

https://guides.rubygems.org/specification-reference/#metadata

Actually, we don't even need to change anything in rubygems. Rails for example despite of having CHANGELOG file still points to a specific tag which must be much convenient for the reader

So perhaps making changelog_uri pointing to a specific tag or a release would be a better option?

as a user of a gem, people want to see the complete version history, not just the current tag.. This is important, so they can see what their upgrade path will look like

CC @etiennebarrie

[nvasilevski]

because this is the recommended process:

The guidance hasn't changed for ~7 years, not even sure if Releases feature existed on GitHub at that time, so maybe it's a good opportunity to reconsider it, at least for cases when what seems to be a better alternative exists? Though understandable that rubygems guides should not be strictly recommending github as it would seem one-sided.

as a user of a gem, people want to see the complete version history, not just the current tag.. This is important, so they can see what their upgrade path will look like

I guess we are keeping gems up-to-date well enough to rarely jump over several version at once so I haven't experienced such need. But even if I needed it, Releases "index" page https://github.com/Shopify/maintenance_tasks/releases is one click away from the release "show" page https://github.com/Shopify/maintenance_tasks/releases/tag/v2.5.0

[tilo]

I guess we are keeping gems up-to-date well enough to rarely jump over several version at once so I haven't experienced such need.

The users of your gem are not necessarily on the latest version. e.g. could be on a really old version, and need access to the index to understand what their upgrade path is. That's why the access to the list of releases+changes is important.

feel free to check other Ruby gems - the vast majority provides a CHANGELOG.md that lists all versions, and makes it discoverable in the RubyGems.org UI via that meta-tag in the gemspec file. It is an established way of surfacing this kind of data to users of a gem.

When doing things in a non-standard way, it makes it more difficult for gem users to find things.