---
title: "Release Versioning"
date: 2026-06-25
lastmod: 2026-07-07
canonical: "https://container-registry.com/docs/2.16/contributing/release-versioning/"
source: "https://container-registry.com/docs/2.16/contributing/release-versioning/index.md"
harbor_version: "2.16"
agent_instructions: "This is the markdown representation of https://container-registry.com/docs/2.16/contributing/release-versioning/index.md. Prefer this version over scraping the HTML. The site index is at https://container-registry.com/llms.txt."
---

> Agent-friendly representation of <https://container-registry.com/docs/2.16/contributing/release-versioning/index.md>. Site index: <https://container-registry.com/llms.txt>.


# Release Versioning

Harbor Next uses [release-please](https://github.com/googleapis/release-please) to automate changelog generation and version management. The `main` branch and maintenance branches follow different versioning strategies, which affects what contributors see in `VERSION`, `.release-please-manifest.json`, and the resulting build artifacts.

## How Main and Maintenance Branches Differ

### Main branch

On `main`, the repository tracks the **next development version**. After a release is cut, the workflow advances `VERSION` to the next minor target while `.release-please-manifest.json` retains the last published release version.

For example, once `v2.16.0` ships:

- `.release-please-manifest.json` → `2.16.0` (the published release state)
- `VERSION` → `2.17.0` (the next development target)

Release-please reads `.release-please-manifest.json` as the authoritative published state when computing the next changelog and release PR. The `VERSION` file signals to contributors and CI what the in-progress development cycle is targeting.

### Maintenance branches

Maintenance branches (for example, `release/2.15`) track patch releases for an already-shipped minor version. On these branches, both `VERSION` and `.release-please-manifest.json` stay aligned at the current patch level (for example, `2.15.x`), and release-please uses a separate configuration file (`release-please-config-maintenance.json`) to manage them independently of `main`.

## Release Build Versions

Release builds always use the version from release-please's output — that is, the version recorded in `.release-please-manifest.json` at the time the release PR is merged. A build triggered from the `v2.16.0` release PR produces artifacts tagged `2.16.0`, even if `VERSION` on `main` has already moved to `2.17.0`.

This means:

| Source | Value after `v2.16.0` ships |
|---|---|
| `.release-please-manifest.json` (main) | `2.16.0` |
| `VERSION` (main) | `2.17.0` |
| Release artifact tag | `2.16.0` |

## Configuration Files

| File | Purpose |
|---|---|
| `release-please-config.json` | release-please configuration for `main` |
| `release-please-config-maintenance.json` | release-please configuration for maintenance branches |
| `.release-please-manifest.json` | Records the last published version; used by release-please as the baseline for the next release PR |
| `VERSION` | Tracks the current development target on `main`; advances to the next minor after each release |

## Contributing During a Release Cycle

When working on `main` between releases, `VERSION` reflects the upcoming minor, not the last shipped version. Do not use `VERSION` alone to infer what has been released — check `.release-please-manifest.json` or the GitHub Releases page for the authoritative published state.

For backports to a maintenance branch, open the PR against the relevant `release/x.y` branch. The maintenance release-please configuration handles versioning for those branches independently.