Why not use GitHub release notes?

[olivierlacan]

@searls offers this example: https://github.com/linemanjs/lineman/releases

My retort:

@searls Sure, but that’s not portable. It’s already hard to convince OSS maintainers to keep a changelog, this is even harder.

Portability

I think the portability problem is a huge showstopper. Something that can't live with the repo will disappear if the project moves from GitHub, or just simply isn't accessible offline with the codebase in hand.

I think that's a problem for GitHub to address if they want to see people adopt their release notes platform.

Tags

This however is a neat idea although I find tags much more obscure than some people seem to realize. The git interface is pretty poor I think, and the visibility from various clients, although better than before, is still not great. That's the one part of GitHub's implementation of Releases notes that I do like, however, since they are portable.

I don't know if it's possible using git, but it would be nice if the GitHub release description was stored in the tag description itself.

[searls]

Hey Github friends (I'll pick on @bkeepers and @leongersing), know who we can talk to that works on Releases? Making their descriptions importable/exportable would probably drive up usage and be a Good Guy Thing™ to do.

[bkeepers]

git tags do allow storing a message with them. I don't know if there's a reason that releases don't use it.

/cc @technoweenie

[technoweenie]

I'd recommend crafting annotated tags first. Releases will use the tag's message as the body by default.

Feel free to hit up support@github.com with more questions about Releases.

[searls]

I didn't even know about annotated git tags. Very cool! For anyone interested and finding this via google, see them documented here: http://git-scm.com/book/en/Git-Basics-Tagging

On Mon, Jul 7, 2014 at 4:42 AM, risk danger olson
notifications@github.com wrote:

I'd recommend crafting annotated tags first. Releases will use the tag's message as the body by default.

Feel free to hit up support@github.com with more questions about Releases.

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

[bkeepers]

Me either. Very cool.

[olivierlacan]

Are any of you folks aware of a tool that could help people create CHANGELOGs by parsing tag notes in a similar way than Releases does?

I mean beyond something like:

for t in `git tag -l`; do git cat-file -p `git rev-parse $t`; done

[Zearin]

👍 for using GitHub Releases. GitHub releases build on top of a seldom-used part of git and make it useful. Let’s take it one step further!

[Zearin]

(Wait; I thought GH Releases use the extended commit message for their notes. Is that incorrect?)

[himedlooff]

In order to avoid duplicating your efforts (maintaining CHANGELOG and Releases) you're forced to choose between the two. What if GitHub tied them together so that you could optionally tie your Releases to your CHANGELOG? It would need to keep them in sync as well so that if you edited the CHANGELOG afterwards, GitHub would also edit the Release.

[mtdowling]

I made a tool that can parse and manage changelog files: https://github.com/mtdowling/chag. It uses a different changelog format than what's proposed by this repo, but it helps with automating creating annotated git tags from changelog entries. You could easily use a changelog file as the canonical source of change, and hook it up to GitHub's releases feature via a Travis-CI deploy hook (so I don't think changelogs and GitHub releases are at odds with each other).

[olivierlacan]

@mtdowling Very interesting. Your format is only marginally different so I don't think it's a big deal. What I really like is the idea that the CHANGELOG is the canonical source of information though. I'm going to play with this some. Thanks. 😃

[Anahkiasen]

I'd love it if Github releases could be exported indeed, find myself copy/pasting from my CHANGELOG to the releases notes all the time

[olivierlacan]

So I've tested annotated Git tags and GitHub releases and it's not there yet.

Given a tag annotation of:

### Fixed
- Loosen ActiveSupport dependency ("~ 3.0" instead of "~ 3.2.0").

This is what GitHub does with the annotation on the tag when it (automatically) creates a Release:

If I attempt to edit the Release to fix this, the pre-existing annotation disappears completely:

I guess the issue is that I tried to produce a change log section with a header (oddly, a third-level one) when there is no pre-existing structure. Perhaps we could individually tag each change with something I've commonly seen:

- [Fixed] Loosen ActiveSupport dependency ("~ 3.0" instead of "~ 3.2.0").

And then worry about extracting these tags into sections (from the annotated tags) later. It would be pretty awesome if GitHub established some basic inline tags based on the ones we gathered here:

• [added]
• [fixed]
• [changed]
• [removed]
• [deprecated]
• [security]

And then GitHub course parse these into a neatly parsed sections for display on the Releases page. What do you think @bkeepers & @technoweenie. Sorry, I'd rather not open a support ticket for this, since we already have a lengthy discussion here. I'll completely understand if you'd rather not discuss product/feature direction stuff here, but I hope the idea is exciting. 😃

[technoweenie]

GitHub uses the same parser for commit and tag messages. Basically, the first line is used as the title, and the rest is the body. That's why ### Fixed is showing up.

We've talked about parsing special release-related tags like you suggest. My suggestion is to do what other great tags do. However, even git doesn't have fancy annotated tag messages.

[olivierlacan]

I've experimented with Releases: https://github.com/olivierlacan/keep-a-changelog/releases

I still find it a bit odd that tag messages aren't used to pre-populate at least the title. The body I can understand. I wish git tags worked like git commit messages that way: title at the first line, body after one new line following the title.

[olivierlacan]

@technoweenie Using git tag -a v0.0.8 --cleanup=whitespace I managed to create a tag message with Markdown (I just made sure to put a release title on the first line).

Now it is sort of weird that release (despite being linked to the tag) doesn't take any hints from the tag message:

[elyscape]

I sent a suggestion in to GitHub about that a week or two ago, actually. Hopefully they implement it sometime.

[mattbrictson]

I just created a tool called "chandler" to sync a project's CHANGELOG.md to GitHub's Releases to solve this problem. It can be manually invoked on the command line, or you can also add it to the Rakefile of a existing Ruby project such that rake release syncs the CHANGELOG to GitHub Releases automatically as part of the rubygems release process. It works by using the GitHub API via octokit.rb.

It is still early days, and I'd like to make it useful for a wider audience. Critique and suggestions are welcome!

https://github.com/mattbrictson/chandler

[Abdillah]

Great tools, @mattbrictson! A wider audience maybe planning for integrating with git (git-chandler) and support more git hosting.

[olivierlacan]

Covered in http://keepachangelog.com/en/1.0.0/#github-releases

[donpaul120]

Im quite a noob in this area but i'd like to know what is the difference between a changelog and a release note? both looks the same to me.

[Mouvedia]

If I attempt to edit the Release to fix this, the pre-existing annotation disappears completely

@olivierlacan does it still happen? Is there a way to avoid the first line auto population?