New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Version release notes #365

Closed
laserlemon opened this Issue Nov 7, 2011 · 21 comments

Comments

Projects
None yet
8 participants
@laserlemon
Contributor

laserlemon commented Nov 7, 2011

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

This comment has been minimized.

Show comment
Hide comment
@stve

stve Nov 14, 2011

Contributor

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.

Contributor

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.

@laserlemon

This comment has been minimized.

Show comment
Hide comment
@laserlemon

laserlemon Nov 14, 2011

Contributor

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.

Contributor

laserlemon commented Nov 14, 2011

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

This comment has been minimized.

Show comment
Hide comment
@qrush

qrush Nov 15, 2011

Member

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.

Member

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.

@jrochkind

This comment has been minimized.

Show comment
Hide comment
@jrochkind

jrochkind Dec 9, 2011

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 commented Dec 9, 2011

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.

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Dec 11, 2011

Contributor

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

Contributor

ognevsky commented Dec 11, 2011

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

@laserlemon

This comment has been minimized.

Show comment
Hide comment
@laserlemon

laserlemon Dec 18, 2011

Contributor

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

Contributor

laserlemon commented Dec 18, 2011

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

@qrush

This comment has been minimized.

Show comment
Hide comment
@qrush

qrush Dec 18, 2011

Member

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.

Member

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.

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Dec 18, 2011

Contributor

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

Contributor

ognevsky commented Dec 18, 2011

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

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Dec 19, 2011

Contributor

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

Contributor

ognevsky commented Dec 19, 2011

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

@laserlemon

This comment has been minimized.

Show comment
Hide comment
@laserlemon

laserlemon Dec 19, 2011

Contributor

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

Contributor

laserlemon commented Dec 19, 2011

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

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Dec 20, 2011

Contributor

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

Contributor

ognevsky commented Dec 20, 2011

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

@cgriego

This comment has been minimized.

Show comment
Hide comment
@cgriego

cgriego Jan 7, 2012

Contributor

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.

Contributor

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

@qrush

This comment has been minimized.

Show comment
Hide comment
@qrush

qrush Jan 8, 2012

Member

That sounds legit! Pull request away :)

On Fri, Jan 6, 2012 at 11:15 PM, Chris Griego <
reply@reply.github.com

wrote:

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.


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

Member

qrush commented Jan 8, 2012

That sounds legit! Pull request away :)

On Fri, Jan 6, 2012 at 11:15 PM, Chris Griego <
reply@reply.github.com

wrote:

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.


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

@benhamill

This comment has been minimized.

Show comment
Hide comment
@benhamill

benhamill Jan 13, 2012

Contributor

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

Contributor

benhamill commented Jan 13, 2012

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

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Jan 13, 2012

Contributor

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

Contributor

ognevsky commented Jan 13, 2012

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

@benhamill

This comment has been minimized.

Show comment
Hide comment
@benhamill

benhamill Jan 15, 2012

Contributor

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.

Contributor

benhamill commented Jan 15, 2012

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.

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Jan 23, 2012

Contributor

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.

Contributor

ognevsky commented Jan 23, 2012

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.

@ognevsky

This comment has been minimized.

Show comment
Hide comment
@ognevsky

ognevsky Jan 23, 2012

Contributor

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.

Contributor

ognevsky commented Jan 23, 2012

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.

@benhamill

This comment has been minimized.

Show comment
Hide comment
@benhamill

benhamill Jan 24, 2012

Contributor

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

Contributor

benhamill commented Jan 24, 2012

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

@olivierlacan

This comment has been minimized.

Show comment
Hide comment
@olivierlacan

olivierlacan Nov 5, 2014

Contributor

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

Contributor

olivierlacan commented Nov 5, 2014

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

This comment has been minimized.

Show comment
Hide comment
@qrush

qrush Nov 28, 2014

Member

Agreed. Closing this issue.

Member

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