diff --git a/README.md b/README.md index ca34d6cb5..6b9692dce 100644 --- a/README.md +++ b/README.md @@ -172,16 +172,10 @@ Vendoring of external imports uses the [`vndr` tool](https://github.com/LK4D4/vn Please refer to [RUNC.md](/RUNC.md) for the currently supported version of `runc` that is used by containerd. -### Releases +### Releases and API Stability -containerd will be released with a 1.0 when feature complete and this version will be supported for 1 year with security and bug fixes applied and released. - -The upgrade path for containerd is that the 0.0.x patch releases are always backward compatible with its major and minor version. -Minor (0.x.0) version will always be compatible with the previous minor release. i.e. 1.2.0 is backwards compatible with 1.1.0 and 1.1.0 is compatible with 1.0.0. -There is no compatibility guarantees with upgrades from two minor releases. i.e. 1.0.0 to 1.2.0. - -There are not backwards compatibility guarantees with upgrades to major versions. i.e 1.0.0 to 2.0.0. -Each major version will be supported for 1 year with bug fixes and security patches. +Please see [RELEASES.md](RELEASES.md) for details on versioning and stability +of containerd components. ### Development reports. diff --git a/RELEASES.md b/RELEASES.md new file mode 100644 index 000000000..c3a828d96 --- /dev/null +++ b/RELEASES.md @@ -0,0 +1,253 @@ +# Versioning and Release + +This document details the versioning and release plan for containerd. Stability +is a top goal for this project and we hope that this document and the processes +it entails will help to achieve that. It covers the release process, versioning +numbering, backporting, API stability and support horizons. + +If you rely on containerd, it would be good to spend time understanding the +areas of the API that are and are not supported and how they impact your +project in the future. + +This document will be considered a living document. Supported timelines, +backport targets and API stability guarantees will be updated here as they +change. + +If there is something that you require or this document leaves out, please +reach out by [filing an issue](https://github.com/containerd/containerd/issues). + +## Releases + +Releases of containerd will be versioned using dotted triples, similar to +[Semantic Version](http://semver.org/). For the purposes of this document, we +will refer to the respective components of this triple as +`..`. The version number may have additional information, +such as alpha, beta and release candidate qualifications. Such releases will be +considered "pre-releases". + +### Major and Minor Releases + +Major and minor releases of containerd will be made from master. Releases of +containerd will be marked with GPG signed tags and announced at +https://github.com/containerd/containerd/releases. The tag will be of the +format `v..` and should be made with the command `git tag +-s v..`. + +After a minor release, a branch will be created, with the format +`release/.` from the minor tag. All further patch releases will +be done from that branch. For example, once we release `v1.0.0`, a branch +`release/1.0` will be created from that tag. All future patch releases will be +done against that branch. + +### Pre-releases + +Pre-releases, such as alphas, betas and release candidates will be conducted +from their source branch. For major and minor releases, these releases will be +done from master. For patch releases, these pre-releases should be done within +the corresponding release branch. + +While pre-releases are done to assist in the stabilization process, no +guarantees are provided. + +### Upgrade Path + +The upgrade path for containerd is such that the 0.0.x patch releases are +always backward compatible with its major and minor version. Minor (0.x.0) +version will always be compatible with the previous minor release. i.e. 1.2.0 +is backwards compatible with 1.1.0 and 1.1.0 is compatible with 1.0.0. There is +no compatibility guarantees for upgrades that span multiple, _minor_ releases. +For example, 1.0.0 to 1.2.0 is not supported. One should first upgrade to 1.1, +then 1.2. + +There are no compatibility guarantees with upgrades to _major_ versions. For +example, upgrading from 1.0.0 to 2.0.0 may require resources to migrated or +integrations to change. Each major version will be supported for at least 1 +year with bug fixes and security patches. + +### Next Release + +The activity for the next release will be tracked in the +[milestones](https://github.com/containerd/containerd/milestones). If your +issue or PR is not present in a milestone, please reach out to the maintainers +to create the milestone or add an issue or PR to an existing milestone. + +### Support Horizon + +Support horizons will be defined corresponding to a release branch, identified +by `.`. Releases branches will be in one of several states: + +- __*Next*__: The next planned release branch. +- __*Active*__: The release is currently supported and accepting patches. +- __*End of Life*__: The release branch is no longer support and no new patches will be accepted. + +Releases will be supported up to one year after a _minor_ release. This means that +we will accept bug reports and backports to release branches until the end of +life date. If no new _minor_ release has been made, that release will be +considered supported until the next _minor_ is released or one year, whichever +is longer. + +The current state is available in the following table: + +| Release | Status | Start | End of Life | +|---------|-------------|------------------|-------------------| +| [0.0](https://github.com/containerd/containerd/releases/tag/0.0.5) | End of Life | Dec 4, 2015 | - | +| [0.1](https://github.com/containerd/containerd/releases/tag/v0.1.0) | End of Life | Mar 21, 2016 | - | +| [0.2](https://github.com/containerd/containerd/tree/v0.2.x) | Active | Apr 21, 2016 | Upon 1.0 release | +| 1.0 | Next | TBD | max(TBD+1 year, release of 1.1.0) | + +Note that branches and release from before 1.0 may not follow these rules. + +This table should be updated as part of the release preparation process. + +### Backporting + +Backports in containerd are community driven. As maintainers, we'll try to +ensure that sensible bugfixes make it into _active_ release, but our main focus +will be features for the next _minor_ or _major_ release. For the most part, +this process is straightforward and we are here to help make it as smooth as +possible. + +If there are important fixes that need to be backported, please let use know in +one of three ways: + +1. Open an issue. +2. Open a PR with cherry-picked change from master. +3. Open a PR with a ported fix. + +__If you are reporting a security issue, please follow the responsible +disclosure guidelines and reach out discreetly__. Remember that backported PRs +must follow the versioning guidelines from this document. + +Any release that is "active" can accept backports. Opening a backport PR is +fairly straightforward. The steps differ depending on whether you are pulling +a fix from master or need to draft a new commit specific to a particular +branch. + +To cherry pick a straightforward commit from master, simply use the cherry pick +process: + +1. Pick the branch to which you want backported, usually in the format + `release/.`. The following will create a branch you can + use to open a PR: + + ```console + $ git checkout -b my-backport-branch release/.. + ``` + +2. Find the commit you want backported. +3. Apply it to the release branch: + + ```console + $ git cherry-pick -xsS + ``` +4. Push the branch and open up a PR against the _release branch_: + + ``` + $ git push -u stevvooe my-backport-branch + ``` + + Make sure to replace `stevvooe` with whatever fork you are using to open + the PR. When you open the PR, make sure to switch `master` with whatever + release branch you are targeting with the fix. + +If there is no existing fix in master, you should first fix the bug in master, +or ask us a maintainer or contributor to do it via an issue. Once that PR is +completed, open a PR using the process above. + +Only when the bug is not seen in master and must be made for the specific +release branch should you open a PR with new code. + +## Public API Stability + +The following table provides an overview of the components covered by +containerd versions: + + +| Component | Status | Stablized Version | Links | +|------------|----------|-------------------|---------------| +| GRPC API | Alpha | 1.0 | [api/](api) | +| Go API | Unstable | 1.1 tentative | [godoc](https://godoc.org/github.com/containerd/containerd) | +| `ctr` tool | Unstable | Out of scope | - | + +From the version stated in the above table, that component must adhere to the +stability constraints expected in release versions. + +Unless explicitly stated here, components that are called out as unstable or +not covered may change in a future minor version. Breaking changes to +"unstable" components will be avoided in patch versions. + +### GRPC API + +The primary product of containerd is the GRPC API. As of the 1.0.0 release, the +GRPC API will not have any backwards incompatible changes without a _major_ +version jump. + +To ensure compatibility, we have collected the entire GRPC API symbol set into +a single file. At each _minor_ release of containerd, we will move the current +`next.pb.txt` file to a file named for the minor version, such as `1.0.pb.txt`, +enumerating the support services and messages. See [api/](api) for details. + +Note that new services may be added in _minor_ releases. New service methods +and new fields on messages may be added if they are optional. + +#### Error Codes + +Error codes will not change in a patch release, unless a missing error code +causes a blocking bug. Error codes of type "unknown" may change to more +specific types in the future. Any error code that is not "unknown" that is +currently returned by a service will not change without a _major_ release or a +new version of the service. + +If you find that an error code that is required by your application is not +well-documented in the protobuf service description or tested explicitly, +please file and issue and we will clarify. + +#### Opaque Fields + +Unless explicitly stated, the formats of certain fields may not be covered by +this guarantee and should be treated opaquely. For example, don't rely on the +format details of a URL field unless we explicitly say that the field will +follow that format. + +### Go API + +The Go API, documented in +[godoc](https://godoc.org/github.com/containerd/containerd), is currently +considered unstable. It is recommended to vendor the necessary components to +stabilize your project build. Note that because the Go API interfaces with the +GRPC API, clients written against a 1.0 Go API should remain compatible with +future 1.x series releases. + +We intend to stabilize the API in a future release when more integrations have +been carried out. + +Any changes to the API should be detectable at compile time, so upgrading will +be a matter of fixing compilation errors and moving from there. + +### `ctr` tool + +The `ctr` tool provides the ability to introspect and understand the containerd +API. At this time, it is not considered a primary offering of the project. It +may be completely refactored or have breaking changes in _minor_ releases. + +We will try not break the tool in _patch_ releases. + +### Not Covered + +As a general rule, anything not mentioned in this document is not covered by +the stability guidelines and may change in any release. Explicitly, this +pertains to this non-exhaustive list of components: + +- File System layout +- Storage formats +- Snapshot formats + +Between upgrades of subsequent, _minor_ versions, we may migrate these formats. +Any outside processes relying on details of these file system layouts may break +in that process. Container root file systems will be maintained on upgrade. + +### Exceptions + +We may make exceptions in the interest of __security patches__. If a break is +required, it will be communicated clearly and the solution will be considered +against total impact.