6.3. Releases

What is a project release?

A project release is a specific version of your project that stabilizes the code and its associated artifacts. It documents a list of changes, bug fixes, and new features aimed at achieving the project's goals. A release serves as a reference point for contributors, enabling them to pinpoint specific software versions that can be utilized in other projects.

Why do you need to create project releases?

Communicate changes to others: Creating a release provides a structured way to inform users and developers about new features, fixes, and improvements. This communication is crucial for managing expectations and helping users to understand how the software has evolved.
Divide the project into milestones: Releases help in setting and achieving milestones throughout the development process. This organization allows teams to track progress, evaluate the effectiveness of the project timeline, and adjust goals as needed.
Ensure each release is stable and consistent: Each release acts as a quality checkpoint, ensuring that the software meets certain standards of stability and consistency. This reduces the risk of regressions and maintains a reliable user experience.

Project releases act as a contract between the contributors and end users. Referencing a specific version, like v8.1.2, guarantees a consistent set of behaviors and interfaces. By maintaining clear and transparent communication about releases, you can build and maintain trust with your user base, especially as the project grows.

At which frequency should you release a new project?

The frequency of new releases varies depending on the project. Some projects benefit from a rapid release cycle, as short as every two or three weeks, while others may opt for longer intervals, possibly every few months. It's crucial to balance the needs of both contributors and users and to establish a clear naming scheme to prevent compatibility issues and conflicts.

Which git workflow should you use for your project?

Choosing an effective git workflow is crucial for streamlined team collaboration and efficient project management. Below are three popular workflows, each with its own strengths and suited for different types of projects.

GitHub Flow

Ideal for projects with frequent releases, GitHub Flow is simple:

Main branch is always deployable.
Feature branches for each new feature or fix.
Use Pull Requests (PRs) for reviews.
Merge into main after review.

Git Flow

More structured, Git Flow is suited for projects with scheduled releases:

Maintain two main branches: master and develop.
Feature branches merge into develop.
Release branches prepare new production releases.
Hotfix branches allow for quick fixes to production.

Forking Workflow

Ideal for open-source projects where multiple external contributors work independently:

Contributors fork the main repo and work independently.
Changes are submitted via PRs from their own forks.
Central maintainers review and merge PRs into the official repository.

Comparison

GitHub Flow is best for small teams or projects needing fast, continuous updates.
Git Flow suits large, complex projects with multiple simultaneous development streams.
Forking Workflow is optimal for projects with broad, diverse contributor bases, particularly in open source.

Choose a workflow based on your project's size, complexity, release frequency, and the nature of your team's collaboration.

Which versioning schema should you use for a project release?

The two most popular versioning schemes are:

SemVer (Semantic Versioning): SemVer is based on three numerical identifiers: major, minor, and patch (e.g., 1.4.2). Major changes include breaking changes, minor changes add functionality in a backwards-compatible manner, and patches are for backwards-compatible bug fixes.
CalVer (Calendar Versioning): CalVer uses the calendar date to inform the version number, which can be useful for projects where time and the state of the project are closely linked, such as in continuously delivered software.

Python also adopts its own version specification scheme known as PEP440, which provides guidelines for version identifiers based on public releases, pre-releases, post-releases, and development releases.

SemVer is recommended for its simplicity and the possibility of communication various level of changes.

How can you create a new project release on GitHub?

Creating a new release on GitHub involves the following steps:

Navigate to your GitHub repository and go to the "Releases" section.
Click on "Draft a new release" or use the tag version from your git command line.
Fill in the tag version, which should match your versioning schema, add release title and description that includes the highlights of this release such as new features, bug fixes, and any deprecations.
Attach binaries or additional relevant files if necessary.
Publish the release, which will then be available to users and can be downloaded from the repository.

How can you prepare and implement a project release with other developers?

Preparing and implementing a release with other developers involves collaboration tools provided by platforms like GitHub:

Issues: Use GitHub Issues to track individual tasks or bugs that need to be addressed before the release.
Labels: Apply labels to issues to categorize them by priority, type (e.g., bug, feature), or status (e.g., in-progress, completed).
Milestones: Group related issues under a milestone corresponding to the release. This helps in tracking progress towards the release and ensures all intended features and fixes are included.

These tools facilitate organization and communication among team members, ensuring that everyone is aligned and aware of the release objectives and timelines.

How can you review and include the work of others in the project release?

Contributors should work on a feature or fix branch specifically created for their task. Once the task is completed:

Feature or fix branch: Developers create branches off the main branch to develop new features or fixes.
Pull Request (PR): They submit a Pull Request to merge their branch into the main branch. The PR should include a clear description of the changes and any necessary documentation updates.
Code Review: Other contributors review the PR, providing feedback and requesting changes if needed. This ensures that the code meets the project’s standards and integrates well with the existing codebase.

After approval, the branch is merged into the main branch, and the feature or fix becomes part of the next release. The feature branch can then be archived.

Which steps should be performed prior to a new project release?

Before releasing, perform these steps:

Testing: Conduct thorough testing, possibly automated using tools like GitHub Actions, to ensure the software works as intended and is free from major bugs.
Publication: Set up a workflow to automatically handle tasks such as documentation updates and container builds upon release.
Changelog: Update the CHANGELOG.md using tools like commitizen, detailing all changes, fixes, and features in this release.

These steps ensure that the release is polished and ready for public use.

Effective communication of changes involves several platforms:

Release page on GitHub: Provides detailed release notes and links to downloadable assets or binaries.
CHANGELOG.md: Maintains a cumulative record of all changes made across releases using the keep a changelog format.
GitHub Pages: Utilizes a version-specific page to provide documentation corresponding to each release.

How long should you support previous releases of your project?

The duration for supporting previous releases depends on the project's scope and user base. For instance, projects like Python provide Long Term Support (LTS) versions that are supported for several years. Define the level of support for each release, which might include backporting critical bug fixes or providing security updates.

A well-documented support policy reassures users that they can rely on your software for critical applications over time.