Skip to content
This repository

Version release notes #365

Open
laserlemon opened this Issue · 19 comments

7 participants

Steve Richert Steve Agalloco Nick Quaranto Jonathan Rochkind Andrey Ognevsky Chris Griego Ben Hamill
Steve Richert
Collaborator

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.

Steve Agalloco

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.

Steve Richert
Collaborator

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.

Nick Quaranto
Owner

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.

Jonathan Rochkind

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.

Andrey Ognevsky

@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.

Steve Richert
Collaborator

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

Nick Quaranto
Owner

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.

Andrey Ognevsky

@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.

Andrey Ognevsky

@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.

Steve Richert
Collaborator

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

Andrey Ognevsky

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

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 rubygems.org linkset.

Nick Quaranto
Owner
Ben Hamill

@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.

Andrey Ognevsky

@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.

Ben Hamill

I've got the sketch of a website that would display changes about a gem over time. Visit (empty database) at http://changems.herokuapp.com or check out the source at http://github.com/benhamill/changems/. 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 rubygems.org 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.

Andrey Ognevsky

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:

header
content

header
content

...

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 Rubygems.org/gems/rails, 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 rubygems.org 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.

Andrey Ognevsky

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'
'## 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) ##'
'2.0.1'
'2.0.0.rc5'
'1.2.4beta2'
'# 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.

Ben Hamill

@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.

Steve Richert laserlemon referenced this issue in rubygems/rubygems
Closed

Gem version release notes #212

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.