Release guide

This document explains how releases are created in this repository, when a new release should be made, and who is allowed to create them.

The release process is intentionally simple:

• all development happens on master
• releases are created from master
• releases are identified with git tags
• each release tag points to one specific commit
• releases are only made after approval
• releases are done together as a team

Overview

This repository uses a single-branch workflow. There is only one main branch: master.

We do not maintain separate long-lived branches such as develop, staging, or release.

A release is made by creating a tag on the exact commit in master that should represent the released version. That means:

• the released code must already exist in master
• the tag is the thing that marks a version as released
• the tag must always point to a known-good commit

When to make a release

A new release should be made when the code in master is considered ready for use.

Typical reasons:

• new features have been completed and tested
• bug fixes are ready to be published
• a milestone or planned version has been reached
• an urgent fix needs to be shipped

A release should not be created for every single commit. Create a release when:

1. the relevant changes are already merged into master
2. the current state of master has been tested
3. the team agrees that there is a clear reason to publish a new version
4. the chosen commit is stable enough to become a reference point
5. approval has been given to proceed with the release

In short: release only from a commit in master that the team has approved and is comfortable supporting.

Who can make releases

Releases are only created:

• after approval has been given
• when the team is aligned on the release commit
• as a coordinated team activity

That means:

• no one should create a release tag without approval
• no one should publish a release alone without team agreement
• the release is a shared team responsibility

In practice, one person may execute the git commands, but the release itself is still considered a team release.

Rules for releases

Follow these rules every time:

• Only release from master
• Never release from a local-only commit
• Never release from an unreviewed or untested state
• Never create a release without approval
• Never move an existing release tag to another commit
• Always make sure the tag points to the exact intended commit

A tag is meant to be permanent. Once a version has been published, that tag should continue to point to the same commit.

Preparing for a release

Before creating a release tag, make sure your local repository matches the latest remote master.

git checkout master
git pull origin master

Then review the current history and identify the commit that should become the release.

Useful commands:

git log --oneline --decorate -n 10
git status

Before tagging, verify:

• you are on master
• your local master is up to date
• the selected commit is the correct one
• the code has been tested as needed
• the team has approved the release
• any version-specific notes are ready

How a release is created

Releasing the current HEAD of master

If the latest commit on master is the release commit:

git checkout master
git pull origin master
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

This creates an annotated tag named v1.2.0 on the current commit and pushes it to the remote.

Releasing a specific earlier commit from master

Sometimes the correct release point is not the latest commit, but an earlier one.

First find the commit hash:

git log --oneline --decorate

Then create the tag on that exact commit:

git tag -a v1.2.0 <commit-hash> -m "Release v1.2.0"
git push origin v1.2.0

Example:

git tag -a v1.2.0 a1b2c3d -m "Release v1.2.0"
git push origin v1.2.0

The release is defined by the tag, and the tag points to one specific commit.

Version tags

Use clear and consistent version names. Recommended format:

• v1.0.0
• v1.1.0
• v1.1.1

General guidance:

• increase the major version for large or breaking changes
• increase the minor version for new backwards-compatible functionality
• increase the patch version for fixes and small corrections

Whatever versioning style the project uses, it should be applied consistently.

Optional GitHub release entry

After pushing the tag, you may also create a GitHub Release based on that tag. A GitHub Release is useful for:

• writing release notes
• summarizing what changed
• giving users a visible release history

If used, make sure the GitHub Release points to the same tag that was pushed.

Quick reference

# Update local master
git checkout master
git pull origin master

# Review recent commits
git log --oneline --decorate -n 10

# Tag current HEAD on master
git tag -a v1.2.0 -m "Release v1.2.0"

# OR tag a specific commit from master
git tag -a v1.2.0 <commit-hash> -m "Release v1.2.0"

# Push tag
git push origin v1.2.0

Release checklist

Before release:

• The code to release is already in master
• master is up to date locally
• The correct commit has been selected
• The selected commit has been tested
• The team has approved the release
• The version number is correct
• The tag name matches the intended release version

During release:

• The release is being done together with the team
• The tag is created on the intended commit
• The correct version tag is pushed

After release:

• The tag has been pushed to origin
• The tag points to the correct commit
• Release notes have been added if needed
• The release has been announced or documented if needed

Important note

Because this repository uses only master, release discipline matters. Do not treat every commit in master as automatically released.

A commit becomes an official release only when it is tagged. That gives us a simple and reliable rule:

master contains the ongoing mainline work, and tags mark the exact commits that are official releases.

Releases are not an individual action. A release is only made after approval and as a coordinated team activity.

Changelog

This page tracks changes between releases of Pynventory.

No formal releases have been tagged yet. This section will be updated as versions are published.