Releases and Tags

GitHub Releases is a feature that sits on top of Git tags and transforms them into polished, user-facing announcements. While a Git tag is a technical pointer to a specific commit, a GitHub release is a presentable package — it includes release notes, downloadable assets, and a clear signal to users that a new version is ready. Releases are how projects communicate change to the people who depend on them.

Tags vs. Releases — The Distinction

These two concepts are related but serve different purposes:

Every GitHub release is backed by a tag. When you create a release on GitHub, you either select an existing tag or create a new one as part of the process. The tag is what Git tracks; the release is what GitHub shows your users.

Creating a Release on GitHub

To create a new release:

1. Go to the repository's main page.
2. Click Releases in the right sidebar (or navigate to the Releases tab).
3. Click Draft a new release.
4. Fill in the release form.

The release form

Writing Good Release Notes

Release notes are the changelog your users read. They answer: what changed in this version and what do I need to know?

A well-structured release note typically includes:

## What's New
- Added dark mode toggle to the settings panel (#47)
- Improved page load performance by 40% on mobile

## Bug Fixes
- Fixed null pointer exception in authentication middleware (#52)
- Resolved session expiry not refreshing the token correctly

## Breaking Changes
- The `config.timeout` property has been renamed to `config.timeoutMs`
  — update your configuration files before upgrading.

## Upgrade Notes
This release requires Node.js 18 or higher.

Auto-generated release notes

GitHub can automatically generate release notes based on the pull requests merged since the last release. On the draft release form, click Generate release notes and GitHub produces a structured list of PRs grouped by label. This is a good starting point — review and edit before publishing, as auto-generated notes benefit from a human pass.

Semantic Versioning for Release Tags

Release tags almost universally follow semantic versioning (SemVer) — vMAJOR.MINOR.PATCH:

Examples: v1.0.0, v1.3.0, v1.3.2, v2.0.0

Pre-release suffixes signal work-in-progress versions:

Examples: v2.0.0-alpha.1, v2.0.0-rc.2

Consistent versioning gives users immediate context: a PATCH bump is safe to upgrade to; a MAJOR bump requires careful review of breaking changes.

Attaching Assets to a Release

GitHub releases can include downloadable files — compiled binaries, zip archives of the source, documentation PDFs, or any distributable file associated with the version.

To attach assets:

1. On the draft release form, drag and drop files onto the Attach binaries section, or click to browse.
2. GitHub uploads and hosts the files.
3. Each file appears as a named download link on the release page.

GitHub automatically includes two default assets for every release:

• Source code (zip) — the repository source at the tagged commit as a .zip.
• Source code (tar.gz) — the same, as a .tar.gz.

These are generated automatically; you do not need to create them manually.

Publishing vs. Saving as Draft

The release form offers two options before you are ready to go public:

• Save as draft — the release is saved but not visible to the public. Useful for preparing the release notes and assets before the launch moment.
• Publish release — the release is immediately visible on the releases page. Watchers of the repository receive a notification.

Draft releases appear in the Releases tab with a "Draft" label visible only to collaborators with write access.

The Releases Page

The releases page (/releases) is the public changelog for your project. It lists all releases in reverse chronological order. The most recent stable release is shown prominently at the top.

Visitors can:

• Read the release notes for each version.
• Download source code archives or attached assets.
• Browse the full history of releases.
• Subscribe to release notifications by watching the repository with the Releases only custom watch option.

Creating a Tag from the Command Line

While GitHub's UI creates tags as part of the release process, you can also create and push a tag from the command line and then create the release on GitHub:

# Create an annotated tag
git tag -a v1.2.0 -m "Release version 1.2.0"

# Push the tag to GitHub
git push origin v1.2.0

Once pushed, the tag appears in GitHub's Tags tab and can be converted into a release from the Releases page — click Create release from tag next to any unpublished tag.

Editing and Deleting Releases

Editing a release

You can edit a release after publishing — to fix a typo in the notes, add a missing asset, or correct a broken link:

1. Go to the release page.
2. Click Edit (pencil icon).
3. Make changes and click Update release.

Deleting a release

Deleting a release removes the release page and any attached assets, but the underlying Git tag is not deleted. To fully remove a tag, delete it separately:

git tag -d v1.2.0                    # Delete locally
git push origin --delete v1.2.0     # Delete on GitHub

Summary