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

Why not use GitHub release notes? #1

Closed
olivierlacan opened this Issue Jun 24, 2014 · 22 comments

Comments

Projects
None yet
@olivierlacan
Owner

olivierlacan commented Jun 24, 2014

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

image

@searls

This comment has been minimized.

searls commented Jun 24, 2014

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

This comment has been minimized.

bkeepers commented Jul 7, 2014

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

This comment has been minimized.

technoweenie commented Jul 7, 2014

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

This comment has been minimized.

searls commented Jul 7, 2014

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

This comment has been minimized.

bkeepers commented Jul 9, 2014

Me either. Very cool.

@olivierlacan

This comment has been minimized.

Owner

olivierlacan commented Jul 10, 2014

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

This comment has been minimized.

Contributor

Zearin commented Aug 14, 2014

👍 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

This comment has been minimized.

Contributor

Zearin commented Aug 14, 2014

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

@himedlooff

This comment has been minimized.

himedlooff commented Aug 15, 2014

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

This comment has been minimized.

mtdowling commented Aug 19, 2014

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

This comment has been minimized.

Owner

olivierlacan commented Aug 19, 2014

@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

This comment has been minimized.

Anahkiasen commented Aug 23, 2014

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

This comment has been minimized.

Owner

olivierlacan commented Sep 1, 2014

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:

image

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

image

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

This comment has been minimized.

technoweenie commented Sep 1, 2014

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

This comment has been minimized.

Owner

olivierlacan commented Dec 13, 2014

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

This comment has been minimized.

Owner

olivierlacan commented Feb 17, 2015

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

image

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

image

@elyscape

This comment has been minimized.

elyscape commented Feb 18, 2015

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

@mattbrictson

This comment has been minimized.

mattbrictson commented Jun 22, 2015

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

This comment has been minimized.

Abdillah commented Jul 18, 2015

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

@olivierlacan

This comment has been minimized.

Owner

olivierlacan commented Jun 23, 2017

olivierlacan pushed a commit that referenced this issue Jul 3, 2017

@emilgoldsmith emilgoldsmith referenced this issue Aug 15, 2017

Closed

Changelog #91

@donpaul120

This comment has been minimized.

donpaul120 commented Aug 21, 2018

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

This comment has been minimized.

Mouvedia commented Aug 25, 2018

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment