InTheForest/moby
1
0
Fork 0
mirror of https://github.com/moby/moby.git synced 2026-01-11 02:31:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

project: Update branches/tags and patch releases

Browse Source 
Signed-off-by: Paweł Gronowski <pawel.gronowski@docker.com>
This commit is contained in:
Paweł Gronowski
2025-12-12 14:59:54 +01:00
parent 4384364748
commit b48be08eb5
2 changed files with 53 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
project/BRANCHES-AND-TAGS.md
View File

@@ -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).

77
project/PATCH-RELEASES.md
View File

@@ -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/<BRANCH_NAME>` label corresponding to the release branch.