Version release notes #365

laserlemon opened this Issue Nov 7, 2011 · 21 comments


None yet

8 participants


Has there been any consideration for release notes attached to gem versions? @bryckbost and I have been talking it over recently and think there's a lot of value in an optional description attached to a new version release. Semantic versioning can only relay so much regarding the impact of a new version (and not everybody uses semantic versioning). A summary of the changes between versions would prove very useful to the gem's users.

As a bonus, a release note could be required when yanking a gem version. Providing the reason behind yanking a version would give a lot of insight into what action should be taken by those gems and projects that depend on that yanked version. Bundler could even (eventually) provide a meaningful message when trying to bundle a yanked gem version.

Thoughts? I am very willing to help out with implementation.

stve commented Nov 14, 2011

How would you propose this be included? As part of gem push? I could envision a standardized changelog format that could be parsed.

I like the idea of providing an explanation when a gem is yanked. Anytime that I've been tripped up by a yanked gem, I typically end up searching the issue log and/or mailing list in search of an explanation, often coming up empty and left wondering.


I suggest gem push nonesuch -m "Hooray for 2.0". Optional on push and required on yank.

As for standardizing a changelog format, the best I've seen are written to be nicely marked up on GitHub and can be not-so-readable in plain text. Release notes for a gem (in my mind) are one-or-two-line, plain text summaries of each version bump. Think commit messages.

qrush commented Nov 15, 2011

I'm still of the opinion that this should be a separate service that can parse changelogs, and be as opinionated as it wants to be. We can link to it next to "Documentation" and "Stats", there's free space there for community services like this.


Is adding a new field to the gemspec is out of the question? There could be a field in the gemspec with a url to the changelog for the version the gemspec currently represents. (It could be a url to a static web page, some yet to be invented third party service, whatever). Then when you push a gem, rubygems could look in that field for a URL to list next to the version item for whatever version you are pushing.

I guess that woudln't work for yankings though. It'd also be too easy for authors to forget to update and include the same changelog with multiple versions accidentally. And it's probably too hard to add a new field to gemspecs anyway.

So wait, okay, how about the "-m" idea on gem push/yank, but it's just a URL. Can still be to a static web page or one of several yet to be invented services, whatever. But it'd be an option for gem push/yank so it could be listed as a link next to the specific version listing, not just a gem-level link like documentation and home page.


@jrochkind i'm developing now a rubygem for parsing changelog files.

I think i publish it next week. And then, on top of this gem, we would be able to create a rails application (separate service, as @qrush said) for listing version's changes.

I don't know if this lib would be useful, but it's a good treetop practice for me.


@ognevsky Any progress on the changelog parser. That's something I'd like to include in

qrush commented Dec 18, 2011

Just as a general point, adding a field to the gemspec is really difficult. Just take a look at lib/rubygems/specification.rb someday :)

That being said we've talked about adding metadata to the gemspec for a long time, but it hasn't shipped yet.


@laserlemon yes, a big progress, in few days i'll publish it. I'll let you know about it.

I'm already parsing changelog header (version and release date) and finishing content (description and other info). Only for markdown for now, but it is not a big problem to code it for textile (or smth else).

It is separate rubygem, then i will create rails app and use it there.


@laserlemon it's no problem to include it to Gemnasium, but Gemnasium is not opensource (as i can see), so i would write my own changelog-application (but you can do with MIT lib what you want). If Gemnasium was opensource (or i was team member), we could join our forces (not to develop 2 similar apps).

And some good news, i think i would publish first version of my gem tonight.


@ognevsky Understood. I'm in complete favor of you writing a changelog app. I'm just excited for the first release too.


@laserlemon having some problems, but would publish in days. I'll report here when it would be done.

cgriego commented Jan 7, 2012

The simplest thing, it seems to me, that would go a long way in helping would be if there was simply a Changelog link in the linkset.

qrush commented Jan 8, 2012

That sounds legit! Pull request away :)

On Fri, Jan 6, 2012 at 11:15 PM, Chris Griego <


The simplest thing, it seems to me, that would go a long way in helping
would be if there was simply a Changelog link in the linkset.

Reply to this email directly or view it on GitHub:
#365 (comment)


@ognevsky: Is your gem in a public repo somewhere? I'd love to pitch in with something related to this. Until I hear from you, I thought I'd play around with some ideas here. Feel free to message me if you want to collaborate.


@benhamill: Because of holidays and my illness, I'm late 'a bit' with publishing it ;(
I think I will completely publish it this weekend.

I'd write here, when I'll done.


I've got the sketch of a website that would display changes about a gem over time. Visit (empty database) at or check out the source at I'd love some feedback (and a pull request with a design). I haven't thought through fully how the DB will get filled, but I imagine something with using the API, downloading source code and @ognevsky's gem all run in a (daily?) background job of some kind. If you'd like to help, please stop over there and open and issue or a pull request, or send me a message.


I totally gave up in this fight with Treetop/Citrus, I can't write some piece of code for left recursion, and nobody could help me ;(

So, I wrote a parser with Treetop which parses headers (like # 3.1.0 (unreleased) or ## 1.0.rc.2 (21 March, 2011) ##), content (the changelog itself) is the rest. But I cannot make recursion to parse this:




So, if somebody have any experience in Treetop (or Citrus, it's faster and simpler a lot) — I ask your help.

About web–service for changelogs. I thought it would be like this:

  • User comes to /rails/3.2.0
  • We know, that he is interested in Rails, version 3.2.0
  • We look in database for this gem and this version
  • If we found something, we render it
  • If not — we send a request to, download this gem, unpack it, try to find some CHANGELOG file by pattern, parse it and write data to database. And, sure, show user these results.
  • If there is no CHANGELOG file, we write this to logs (to check it manually later) and say user, that there is no success.

Or, maybe, at step download the gem from we should download exact this version (3.2.0 in my example) and parse only last header/content pair. So, it would be faster and we don't need left recursion to parse all file.

So, anyway, I need some help. I've created memoirs organization to store there memoirs gem, which will auto–download all memoirs-gems (memoirs-markdown, memoirs-textile, etc) and those memoirs-gems itself. I can push my code (with specs) there and we can have some fun there.

Anyway, sorry for this long delay in developing this.


Now I have Treetop grammar, that parses these types of headers (I've extracted them from my specs, so everything is 100% covered):

'#1 '
' #1'
'# 1 #'
'## 1 ##'
'## 1'
'# 1.0'
'# 0.9.5'
'# 1.0.pre.1'
'## Rails 3.1.1 (October 7, 2011) ## '
'## Rails 3.2.0 (unreleased) ##'
'## Rails 3.2.0 ##'
'## 2.2.1 RC2 (November 14th, 2008) ##'
'# Version 1.3.0'
'# Version 0.7'
'# 1 (Oct 3, 2011)'
'# 1 (Oct 03, 2011'
'# 1 (May 10th, 2011)'
'# 1 (unreleased)'
'# 1 (unpublished)'

This all is real-project ways to write markdown headers.


@ognevsky My changems project has come a long way since I last posted. I'll send you a message directly with more information, but check out what I did with the Treetop stuff. I have it importing Rails' sub-gems (activerecord, etc.) change logs in a reasonable amount of time locally. Having some deployment issue with Heroku that I need to track down. Pop on over to the repo (or link me to yours or send me an email) and we can compare notes.


As #212 was rejected, I think #578 might be a better approach. Smaller scope, easier to implement, and almost as valuable one click away.

qrush commented Nov 28, 2014

Agreed. Closing this issue.

@qrush qrush closed this Nov 28, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment