13. Packages & Releases

When your software reaches a stable point, you want to package it up and deliver it to your users. GitHub provides **Releases** to help you distribute compiled binaries, installation files, and source code, along with **GitHub Packages** to host software dependency registries (like NPM, Docker, or NuGet packages). In this chapter, we will learn how to create and manage releases.

1. What is a GitHub Release?

A GitHub Release is a dedicated download page on your repository based on a specific Git tag. It contains:

• A version tag name (e.g., v1.0.0).
• A descriptive release title and changelog summary of all additions/fixes.
• Downloadable assets (compiled `.exe` files, desktop installer packages, or zipped source code).

2. How to Create a Release on GitHub

1. Go to your repository homepage.
2. On the right-hand sidebar menu under "Releases", click "Create a new release" (or click the Releases header).
3. Click "Choose a tag". You can type a new tag name (e.g., v1.0.0) or select an existing tag.
4. Specify the target branch (usually main).
5. Give the release a title (e.g., v1.0.0 - Stable Release).
6. Write your release notes. You can click "Generate release notes" to have GitHub automatically build a checklist of all merged pull requests and contributors since your last release!
7. Drag and drop compiled assets (like a `.zip`, `.dmg`, or `.exe` installer) into the attachment box.
8. If the software is not fully tested, check the box for "This is a pre-release" to notify users.
9. Click "Publish release".

3. Understanding Semantic Versioning (SemVer)

When tagging releases, professional developers follow the **Semantic Versioning (SemVer)** structure:

Each number represents specific change scales:

• MAJOR (2.x.x): Incremented when you make **breaking API changes** that are incompatible with older versions.
• MINOR (x.1.x): Incremented when you add **new features** in a backwards-compatible manner.
• PATCH (x.x.4): Incremented when you release **backwards-compatible bug fixes**.

4. Distributing Assets via GitHub Packages

While Releases distribute software to end users, GitHub Packages distributes package libraries to developers. It integrates seamlessly with standard package managers:

• npm: Publish JavaScript packages.
• Docker: Host container images in the GitHub Container Registry.
• NuGet / Maven: Publish .NET / Java packages.

You can configure your GitHub Actions workflow to automatically publish NPM packages or build Docker containers every time a new Release is published, creating a complete automated pipeline!