What exactly is a Release in GitHub?

Question

• What is it exactly?
• For what is it used?
• How widespread is the usage?
• How is it usually used?

Answer 1

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.

Answer 2

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:

1. A release is initially "empty" because it is associated with a tag, not generated from that tag
2. 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.

---

And from June 2022, you can set/change/modify a release notes for a previous release (or past release):

You can now manually select a previous release when generating release notes

It is now possible to manually select the previous release prior to generating release notes in the GitHub Releases UI.

For more information on Generating Release Notes, see the Automatically Generated Release Notes documentation. For more information on GitHub Releases, see the GitHub Releases documentation.