project: Update branches/tags and patch releases

Signed-off-by: Paweł Gronowski <pawel.gronowski@docker.com>

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                                       |
+| docker-29.x                 | The Moby Project [MAINTAINERS](../MAINTAINERS) | Maintained            | After docker-30.x           | [Docker, Inc.][docker], [Microsoft][msft] |
-| 28.x                        | The Moby Project [MAINTAINERS](../MAINTAINERS) | Maintained            | After 29.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).

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
+The patch releases can be cut straight from the `master` branch if there are no
-release. Docker open source projects follow these procedures when creating a
+changes that would warrant a non-patch release.
-patch release;
 
-After each release (both "major" (vX.Y.0) and "patch" releases (vX.Y.Z)), a
+However, if the `master` branch has changes that are not suitable for a patch
-patch release milestone (vX.Y.Z + 1) is created.
+release, a release branch should be created.
 
-The creation of a patch release milestone is no obligation to actually
+See [BRANCHES-AND-TAGS.md](BRANCHES-AND-TAGS.md) for more information on the release branches.
-*create* a patch release. The purpose of these milestones is to collect
-issues and pull requests that can *justify* a patch release;
 
-- Any maintainer is allowed to add issues and PR's to the milestone, when
+## Backporting changes
-  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.
 
-The release captain of the "major" (X.Y.0) release, is also responsible for
+If a release branch exists (because `master` has changes that are not suitable for
-patch releases. The release captain, together with another maintainer, will
+a patch release), then bug fixes and patches need to be backported to that release
-review issues and PRs on the milestone, and assigns `priority/`labels. These
+branch. If patches can be shipped directly from `master`, no backporting is needed.
-review sessions take place on a weekly basis, more frequent if needed:
 
-- A P0 priority is assigned to critical issues. A maintainer *must* be
+A patch must:
-  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.
 
-## 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.
+To indicate that a pull request made against the `master` branch should be
-- P1, P2, and P3 issues/PR's should not influence the decision, and
+included in the next patch release, the author or maintainer should apply a
-  should be moved to the X.Y.Z+1 milestone, or removed from the
+`process/cherry-pick/<BRANCH_NAME>` label corresponding to the release branch.
-  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.