What exactly is a Release in GitHub?
From Official GitHub:
Releases are GitHub's way of packaging and providing software to your users. You can think of it as a replacement to using downloads to provide software.
With Releases, you can provide links to binary files, as well as release notes describing your changes.
At their core, Releases are based on Git tags. Tags mark a specific point in the history of your project, so they're a great way to indicate a Release. Releases are ordered by a tag's date in the following way:
- If it's an annotated tag, the tag object's date is used.
- If it's a lightweight tag, then the commit object's date is used.
For more information about viewing your existing tags, see Working With Tags.
I would like to backup this official explanation from people who are already using that to see how it works.
Definition
As mentioned in "About Releases"
Releases are GitHub's way of packaging and providing software to your users. You can think of it as a replacement to using downloads to provide software.
A release is a container of one or more assets, associated to a git annotated tag (since git push --follow-tags only pushes annotated tags)
It replaces since July 2013 an old "GitHub Download" system which was beginning to get abused (people stored anything and everything in it), and removed in Dec. 2012.
By forcing an indirection (tag => release => asset), GitHub made that feature more manageable.
dirkjot adds in the comments:
Two great points that are easily overlooked:
- A release is initially "empty" because it is associated with a tag, not generated from that tag
- Assets are uploaded so not necessarily related to the source code.
Footnote: An empty release will automatically contain a tgz and zip version of the source at the tagged commit
Usage
A GitHub release is used:
- to avoid storing large generated binaries built from project in a source control system like git.
- by users of a repo to download the "end result", ie the "delivery" already built for them from a git repo content, even if they don't have git.
Example
An example of a project using releases would be git for windows releases.
In the case of git for Windows, that comes in handy considering that you might want to install git in the first place, and you might not have the right tool-set to compile its sources.
API consideration
As the GitHub V3 Release API illustrates, a release is not a tag.
When you create a release, you would need the name of a tag, but that would create an empty release (associated to that tag)
From a release, you can upload one or more assets to it.
The asset data is expected in its raw binary form.
POST https://<upload_url>/repos/:owner/:repo/releases/:id/assets?name=foo.zip
Note: GitLab also supports "release" since GitLab 8.2 (Nov. 2015).
Discussion
Since Apr. 2021, you now have:
Releases support comments and reactions with Discussion linking
You can now link discussions to new releases!
When drafting a new release, check the Create a discussion for this release box, choose a category, and publish.
Your community will be able to react and comment on the release notes, giving projects more opportunities to celebrate and receive feedback.
Release discussions are also available natively on GitHub Mobile.
For more information, see GitHub Discussions, GitHub Releases and GitHub Mobile documentation.
Note that in Q3 2021, you could have a native changelog generator.