Make release date optional ?

[gonzoyumo]

Asked on twitter by @sferik:

What do you think about making the release date in the version header optional?

Sample changelog extracted from sferik/twitter:

4.5.0

• Add no_retweet_ids (@tibbon)

  4.4.4

• Fix documentation bugs
• Relax multi_json dependency

[gonzoyumo]

I would advocate for keeping them for these reasons:

• it gives a quick insight of the project activity
• some languages's libraries don't embed a build date which makes finding that information really hard (need to read commits)

Changelog should be THE place where to look for changes information, and when talking about changes, dates feel important to me.

Except laziness, what makes you think it shouldn't be present? I maybe missed something...

[gravis]

We are spending hours on changelogs, and I have to agree with Olivier :)

On 15 févr. 2013, at 23:48, Olivier Gonzalez notifications@github.com wrote:

I would advocate for keeping them for these reasons:

• it gives a quick insight of the project activity
• some languages's libraries don't embed a build date which makes finding that information really hard (need to read commits)

Changelog should be THE place where to look for changes information, and when talking about changes, dates feel important to me.

Except laziness, what makes you think it shouldn't be present? I maybe missed something...

— Reply to this email directly or view it on GitHubhttps://github.com/tech-angels/vandamme/issues/2#issuecomment-13632378.

[sferik]

I can't speak for other languages, but in Ruby, the canonical release date is available from RubyGems.org. For example: https://rubygems.org/gems/gems/versions

Once you have parsed out the release number from the Changelog, you could use the RubyGems.org API (via the gems gem) to find the official release date for each version (provided in ISO 8601 format). This has the benefit of being the actual date when the gem was pushed to RubyGems.org, so it is guaranteed to be correct and this information does not need to be duplicated (where there could be an error or ambiguity) in the CHANGELOG.

I understand you don’t want the CHANGELOG format to be Ruby-specific—and I'm okay with having the date after a slash be optional—but I don't understand why it needs to be mandatory. If it is mandatory, then I probably won’t embrace the CHANGELOG format.

[sferik]

Also, if you're going to specify a date, you should specify the expected format. From the example, it appears to be YYYY-MM-DD, but you don't specify that anywhere.

[sferik]

Also, there's a typo in the title of this issue. It should say "date" not "data". Release data is not optional. :stuck_out_tongue_winking_eye:

[sferik]

In general, I believe the CHANGELOG format should attempt to codify existing community standards and best practices, not define new standards. If the date is optional, most CHANGELOGs will already conform to this standard. If it's mandatory, most CHANGELOGs will need to be updated, which will probably never happen.

[gonzoyumo]

Title typo fixed, thx :)

Release date are indeed available on rubygems.org for rubygems but it forces the user to go there to find the information :(

About date format, the suggested format is "2013-02-14" (ISO 8601) as shown in the example, but it should indeed be added explicitly in convention once (and if) accepted.

I agree we should find a convention that is near to the most used format to limit updates, but I also advocate for the most useful format.

And as you talk about parsing, I just want to make things clear: this project really aim to find the better format to allow user to get information, not to suit the needs of a specific parser. Even if, of course, one of the benefit of a common format is to be able to parse it.

Thanks a lot for your advice, you're maintaining a lot of rubygems so we really appreciate your knowledge and your participation. Would be great to have more people involved to have their opinion on this.

[nathany]

My concern with making the release date mandatory was updating existing CHANGELOGs. But seeing as those can be retrieved from https://rubygems.org/gems/gems/versions, it's not so bad. I think it would be great if RubyGems used the same date format, or better yet, adopted Vandamme for displaying change logs.

[sferik]

@nathany Just to be clear, I'm proposing using the RubyGems.org API, which returns build timestamps in ISO 8601 format. This format can be easily parsed into any other time format of your choosing. Could you say more about your wish for RubyGems.org to adopt Vandamme for displaying CHANGELOGs? In general, RubyGems.org prefers to provide APIs so that these services can be operated independently. This way RubyGems.org can focus on being a gem server and other services, like Gemnasium, can focus on their core objectives.

[sferik]

Release date are indeed available on rubygems.org for rubygems but it forces the user to go there to find the information :(

@gonzoyumo I thought the motivation for making CHANGELOGs parseable is so the information could be provided as a service, similar to Gemnasium. If such a service could parse CHANGELOGs, there's no reason why it couldn’t correlate version data to release data from the RubyGems.org API.

I still haven’t heard a compelling argument for why dates must be mandatory. I understand why they might be nice to have, but do you really want the parser to raise an exception if the date is missing? That seems rather extreme for information that seems non-essential and is available elsewhere.

[nathany]

@sferik In that case, I would minimally like to see RubyGems link to the CHANGELOG, whether the file in a source repository, or to a page on Gemnasium. (Update: I see there is already a PR for that https://github.com/rubygems/rubygems.org/pull/400). I quite like what TechAngels is trying to do here, having spent too much time looking for Changes/History files and falling back to commit logs. Hopefully this catches on.

I think requiring a small gem like Vandamme to depend on the RubyGems API is a little much. If an author could easily grab the properly formatted MAJOR.MINOR.PATCH / YYYY-MM-DD versions from RubyGems.org or via the CLI, it would take a matter of minutes to update their CHANGELOG.

That said, I'm not set on mandatory dates either. For the most part, I'm looking at the version # I have now and scrolling up through changes to the current version.

[gravis]

As said in #3, if we make the format too open, we won't be able to parse file efficiently. Also, the goal of these rules is to provide a standard format for any changelog file, not only rubygems, so we can't rely on external services for that. Some projects don't even tag their code, so release date is a good thing to have in the changelog I think.

Also, there's no way this convention will work for a lot of existing changelogs, so we shouldn't give so much attention to find something that will suit as many files as possible. Remember that a lot of projects don't rely on semver, so versions numbers really vary a LOT :( My idea behind the convention is to help new comers when they wonder what format they should use. They often stick to their favorite framework format, without being sure.

I don't see what's the hard part in adding the current date when I edit a file anyway :) I understand old changelog files will need some update, but as we're creating a LOT of regexp for gemnasium already, we can propose pull requests in the mean time (that's generally what we do).

[gonzoyumo]

@sferik, @nathany actually Gemnasium already provides changelog for some gems (see devise gem) and it doesn't relies on Vandamme to get the release dates nor expect them to be mandatory. So Vandamme is also capable to parse multiple different Readme's syntaxes (using their own regexp) and if you don't follow convention, it doesn't mean you won't be parseable (though it won't be automatic and it will require more work).

As @gravis said, here the goal is to find "the best" (as much as possible) syntax that may be followed starting from now (at least, when it will be fixed ^^)

As an argument for mandatory date, I may repeat what I already said: to me, a change is a modification of something at a given time. And it allows unreleased changes syntax (see #1) I also think the cost to put the date next to release number when adding the entry in the Readme is worth the effort all the users will need to go on other sources to find that information.

[sferik]

As an argument for mandatory date, I may repeat what I already said: to me, a change is a modification of something at a given time.

This is not an argument for why it should be mandatory. This is an argument for why it would be nice to have. By making it mandatory, what you’re saying is: “If a release doesn’t have a date, I will not parse it.” If you parse it anyway, then the date is not mandatory, it is optional.