From b48be08eb5e65d3746f01004f9824a7693875a34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Gronowski?= Date: Fri, 12 Dec 2025 14:59:54 +0100 Subject: [PATCH] project: Update branches/tags and patch releases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Paweł Gronowski --- project/BRANCHES-AND-TAGS.md | 40 +++++++++++++++++-- project/PATCH-RELEASES.md | 77 ++++++++---------------------------- 2 files changed, 53 insertions(+), 64 deletions(-) diff --git a/project/BRANCHES-AND-TAGS.md b/project/BRANCHES-AND-TAGS.md index 85986e2544..11b7853452 100644 --- a/project/BRANCHES-AND-TAGS.md +++ b/project/BRANCHES-AND-TAGS.md @@ -3,20 +3,39 @@ Branches and tags > Note: details of the release process of the project are documented in [PATCH-RELEASES.md](PATCH-RELEASES.md). +# Overview + +The Moby Project repository contains multiple components with their own versioning: + +- **Moby** - the core library, versioned as `v2.x` (currently in beta) +- **Docker Engine** - built from this repository, versioned independently +- **API** (`api/`) - a separate Go module of the client library +- **Client** (`client/`) - a separate Go module containing the materialization of the API specification, follows API versioning + # Branches `master` serves as the development branch for future releases of the project. -All changes should be made to the `master` branch, and changes to release branches should only be made in the form of cherry-picked commits, if possible. +All changes should be made to the `master` branch. +When possible, Moby/Docker Engine releases are cut directly from `master`. +Release branches are created when ongoing development on `master` would conflict with patch releases. The sponsoring maintainers of a release branch serve as the primary point of contact, and are available to provide guidance on contributing changes to their respective branches. -Keep in mind that release branches only accept bug and security fixes; new features will generally not be considered for backport to release branches. +A single release branch can be used for the whole release cycle of a major version or a specific minor version line. +For example, the `docker-29.x` branch is used for the release cycle of the `29` major version and all minor versions within it. +A historical example of the latter approach are the `26.0` and `26.1` branches, which were used for separate minor versions within the `26` major version. + +It is up to the sponsoring maintainers to decide whether to use a single release branch for the whole release cycle of a major version or a specific minor version line. + +## Docker Engine Branches + +Docker Engine release branches use the format `docker-MAJOR.x` (e.g., `docker-29.x`). Currently (and previously) maintained release branches are documented in the table below: | Branch Name | Sponsoring Maintainer(s) | Contribution Status | Expected End of Maintenance | Known Distributors | |-----------------------------|------------------------------------------------|-----------------------|-----------------------------|-------------------------------------------| -| master (development branch) | The Moby Project [MAINTAINERS](../MAINTAINERS) | N/A | - | N/A | -| 28.x | The Moby Project [MAINTAINERS](../MAINTAINERS) | Maintained | After 29.x | [Docker, Inc.][docker], [Microsoft][msft] | +| docker-29.x | The Moby Project [MAINTAINERS](../MAINTAINERS) | Maintained | After docker-30.x | [Docker, Inc.][docker], [Microsoft][msft] | +| docker-28.x | @cpuguy83 | Maintained | TBD | [Microsoft][msft] | | 27.x | | Unmaintained | | | | 26.1 | | Unmaintained | | | | 26.0 | | Unmaintained | | | @@ -52,3 +71,16 @@ The general format of a tag is `vX.Y.Z[-suffix[N]]`: - All of `X`, `Y`, `Z` must be specified (example: `v1.0.0`) - First release candidate for version `1.8.0` should be tagged `v1.8.0-rc1` - Second alpha release of a product should be tagged `v1.0.0-alpha1` + +## Tag Prefixes + +Different components use different tag prefixes: + +| Component | Tag Format | Example | +|---------------|-------------------------|-------------------| +| Moby | `vX.Y.Z` | `v2.0.0-beta.5` | +| Docker Engine | `docker-vX.Y.Z` | `docker-v29.1.2` | +| API | `api/vX.Y.Z` | `api/v1.52.0` | +| Client | `client/vX.Y.Z` | `client/v1.52.0` | + +For the current release state, see [GitHub Releases](https://github.com/moby/moby/releases). diff --git a/project/PATCH-RELEASES.md b/project/PATCH-RELEASES.md index 548db9ab4d..26be66c0f9 100644 --- a/project/PATCH-RELEASES.md +++ b/project/PATCH-RELEASES.md @@ -1,68 +1,25 @@ -# Docker patch (bugfix) release process +# Patch (bugfix) release process -Patch releases (the 'Z' in vX.Y.Z) are intended to fix major issues in a -release. Docker open source projects follow these procedures when creating a -patch release; +The patch releases can be cut straight from the `master` branch if there are no +changes that would warrant a non-patch release. -After each release (both "major" (vX.Y.0) and "patch" releases (vX.Y.Z)), a -patch release milestone (vX.Y.Z + 1) is created. +However, if the `master` branch has changes that are not suitable for a patch +release, a release branch should be created. -The creation of a patch release milestone is no obligation to actually -*create* a patch release. The purpose of these milestones is to collect -issues and pull requests that can *justify* a patch release; +See [BRANCHES-AND-TAGS.md](BRANCHES-AND-TAGS.md) for more information on the release branches. -- Any maintainer is allowed to add issues and PR's to the milestone, when - doing so, preferably leave a comment on the issue or PR explaining *why* - you think it should be considered for inclusion in a patch release. -- Issues introduced in version vX.Y.0 get added to milestone X.Y.Z+1 -- Only *regressions* should be added. Issues *discovered* in version vX.Y.0, - but already present in version vX.Y-1.Z should not be added, unless - critical. -- Patch releases can *only* contain bug-fixes. New features should - *never* be added to a patch release. +## Backporting changes -The release captain of the "major" (X.Y.0) release, is also responsible for -patch releases. The release captain, together with another maintainer, will -review issues and PRs on the milestone, and assigns `priority/`labels. These -review sessions take place on a weekly basis, more frequent if needed: +If a release branch exists (because `master` has changes that are not suitable for +a patch release), then bug fixes and patches need to be backported to that release +branch. If patches can be shipped directly from `master`, no backporting is needed. -- A P0 priority is assigned to critical issues. A maintainer *must* be - assigned to these issues. Maintainers should strive to fix a P0 within a week. -- A P1 priority is assigned to major issues, but not critical. A maintainer - *must* be assigned to these issues. -- P2 and P3 priorities are assigned to other issues. A maintainer can be - assigned. -- Non-critical issues and PR's can be removed from the milestone. Minor - changes, such as typo-fixes or omissions in the documentation can be - considered for inclusion in a patch release. +A patch must: -## Deciding if a patch release should be done +- Not be a major/new feature +- Not break existing functionality +- Be a bugfix or a small improvement -- Only a P0 can justify to proceed with the patch release. -- P1, P2, and P3 issues/PR's should not influence the decision, and - should be moved to the X.Y.Z+1 milestone, or removed from the - milestone. - -> **Note**: If the next "major" release is imminent, the release captain -> can decide to cancel a patch release, and include the patches in the -> upcoming major release. - -> **Note**: Security releases are also "patch releases", but follow -> a different procedure. Security releases are developed in a private -> repository, released and tested under embargo before they become -> publicly available. - -## Deciding on the content of a patch release - -When the criteria for moving forward with a patch release are met, the release -manager will decide on the exact content of the release. - -- Fixes to all P0 issues *must* be included in the release. -- Fixes to *some* P1, P2, and P3 issues *may* be included as part of the patch - release depending on the severity of the issue and the risk associated with - the patch. - -Any code delivered as part of a patch release should make life easier for a -significant amount of users with zero chance of degrading anybody's experience. -A good rule of thumb for that is to limit cherry-picking to small patches, which -fix well-understood issues, and which come with verifiable tests. +To indicate that a pull request made against the `master` branch should be +included in the next patch release, the author or maintainer should apply a +`process/cherry-pick/` label corresponding to the release branch.