github.com/demonoid81/containerd@v1.3.4/RELEASES.md (about) 1 # Versioning and Release 2 3 This document details the versioning and release plan for containerd. Stability 4 is a top goal for this project and we hope that this document and the processes 5 it entails will help to achieve that. It covers the release process, versioning 6 numbering, backporting, API stability and support horizons. 7 8 If you rely on containerd, it would be good to spend time understanding the 9 areas of the API that are and are not supported and how they impact your 10 project in the future. 11 12 This document will be considered a living document. Supported timelines, 13 backport targets and API stability guarantees will be updated here as they 14 change. 15 16 If there is something that you require or this document leaves out, please 17 reach out by [filing an issue](https://github.com/containerd/containerd/issues). 18 19 ## Releases 20 21 Releases of containerd will be versioned using dotted triples, similar to 22 [Semantic Version](http://semver.org/). For the purposes of this document, we 23 will refer to the respective components of this triple as 24 `<major>.<minor>.<patch>`. The version number may have additional information, 25 such as alpha, beta and release candidate qualifications. Such releases will be 26 considered "pre-releases". 27 28 ### Major and Minor Releases 29 30 Major and minor releases of containerd will be made from master. Releases of 31 containerd will be marked with GPG signed tags and announced at 32 https://github.com/containerd/containerd/releases. The tag will be of the 33 format `v<major>.<minor>.<patch>` and should be made with the command `git tag 34 -s v<major>.<minor>.<patch>`. 35 36 After a minor release, a branch will be created, with the format 37 `release/<major>.<minor>` from the minor tag. All further patch releases will 38 be done from that branch. For example, once we release `v1.0.0`, a branch 39 `release/1.0` will be created from that tag. All future patch releases will be 40 done against that branch. 41 42 ### Pre-releases 43 44 Pre-releases, such as alphas, betas and release candidates will be conducted 45 from their source branch. For major and minor releases, these releases will be 46 done from master. For patch releases, these pre-releases should be done within 47 the corresponding release branch. 48 49 While pre-releases are done to assist in the stabilization process, no 50 guarantees are provided. 51 52 ### Upgrade Path 53 54 The upgrade path for containerd is such that the 0.0.x patch releases are 55 always backward compatible with its major and minor version. Minor (0.x.0) 56 version will always be compatible with the previous minor release. i.e. 1.2.0 57 is backwards compatible with 1.1.0 and 1.1.0 is compatible with 1.0.0. There is 58 no compatibility guarantees for upgrades that span multiple, _minor_ releases. 59 For example, 1.0.0 to 1.2.0 is not supported. One should first upgrade to 1.1, 60 then 1.2. 61 62 There are no compatibility guarantees with upgrades to _major_ versions. For 63 example, upgrading from 1.0.0 to 2.0.0 may require resources to migrated or 64 integrations to change. Each major version will be supported for at least 1 65 year with bug fixes and security patches. 66 67 ### Next Release 68 69 The activity for the next release will be tracked in the 70 [milestones](https://github.com/containerd/containerd/milestones). If your 71 issue or PR is not present in a milestone, please reach out to the maintainers 72 to create the milestone or add an issue or PR to an existing milestone. 73 74 ### Support Horizon 75 76 Support horizons will be defined corresponding to a release branch, identified 77 by `<major>.<minor>`. Releases branches will be in one of several states: 78 79 - __*Next*__: The next planned release branch. 80 - __*Active*__: The release branch is currently supported and accepting patches. 81 - __*Extended*__: The release branch is only accepting security patches. 82 - __*End of Life*__: The release branch is no longer supported and no new patches will be accepted. 83 84 Releases will be supported up to one year after a _minor_ release. This means that 85 we will accept bug reports and backports to release branches until the end of 86 life date. If no new _minor_ release has been made, that release will be 87 considered supported until 6 months after the next _minor_ is released or one year, 88 whichever is longer. Additionally, releases may have an extended security support 89 period after the end of the active period to accept security backports. This 90 timeframe will be decided by maintainers before the end of the active status. 91 92 The current state is available in the following table: 93 94 | Release | Status | Start | End of Life | 95 |---------|-------------|------------------|-------------------| 96 | [0.0](https://github.com/containerd/containerd/releases/tag/0.0.5) | End of Life | Dec 4, 2015 | - | 97 | [0.1](https://github.com/containerd/containerd/releases/tag/v0.1.0) | End of Life | Mar 21, 2016 | - | 98 | [0.2](https://github.com/containerd/containerd/tree/v0.2.x) | End of Life | Apr 21, 2016 | December 5, 2017 | 99 | [1.0](https://github.com/containerd/containerd/releases/tag/v1.0.3) | End of Life | December 5, 2017 | December 5, 2018 | 100 | [1.1](https://github.com/containerd/containerd/releases/tag/v1.1.8) | Extended | April 23, 2018 | October 23, 2019 | 101 | [1.2](https://github.com/containerd/containerd/releases/tag/v1.2.10) | Active | October 24, 2018 | March 26, 2020 | 102 | [1.3](https://github.com/containerd/containerd/releases/tag/v1.3.0) | Active | September 26, 2019 | max(September 26, 2020, release of 1.4.0 + 6 months) | 103 | [1.4](https://github.com/containerd/containerd/milestone/27) | Next | TBD | max(TBD+1 year, release of 1.5.0 + 6 months) | 104 105 Note that branches and release from before 1.0 may not follow these rules. 106 107 This table should be updated as part of the release preparation process. 108 109 ### Backporting 110 111 Backports in containerd are community driven. As maintainers, we'll try to 112 ensure that sensible bugfixes make it into _active_ release, but our main focus 113 will be features for the next _minor_ or _major_ release. For the most part, 114 this process is straightforward and we are here to help make it as smooth as 115 possible. 116 117 If there are important fixes that need to be backported, please let use know in 118 one of three ways: 119 120 1. Open an issue. 121 2. Open a PR with cherry-picked change from master. 122 3. Open a PR with a ported fix. 123 124 __If you are reporting a security issue, please reach out discreetly at security@containerd.io__. 125 Remember that backported PRs must follow the versioning guidelines from this document. 126 127 Any release that is "active" can accept backports. Opening a backport PR is 128 fairly straightforward. The steps differ depending on whether you are pulling 129 a fix from master or need to draft a new commit specific to a particular 130 branch. 131 132 To cherry pick a straightforward commit from master, simply use the cherry pick 133 process: 134 135 1. Pick the branch to which you want backported, usually in the format 136 `release/<minor>.<major>`. The following will create a branch you can 137 use to open a PR: 138 139 ```console 140 $ git checkout -b my-backport-branch release/<major>.<minor>. 141 ``` 142 143 2. Find the commit you want backported. 144 3. Apply it to the release branch: 145 146 ```console 147 $ git cherry-pick -xsS <commit> 148 ``` 149 4. Push the branch and open up a PR against the _release branch_: 150 151 ``` 152 $ git push -u stevvooe my-backport-branch 153 ``` 154 155 Make sure to replace `stevvooe` with whatever fork you are using to open 156 the PR. When you open the PR, make sure to switch `master` with whatever 157 release branch you are targeting with the fix. 158 159 If there is no existing fix in master, you should first fix the bug in master, 160 or ask us a maintainer or contributor to do it via an issue. Once that PR is 161 completed, open a PR using the process above. 162 163 Only when the bug is not seen in master and must be made for the specific 164 release branch should you open a PR with new code. 165 166 ## Public API Stability 167 168 The following table provides an overview of the components covered by 169 containerd versions: 170 171 172 | Component | Status | Stabilized Version | Links | 173 |------------------|----------|--------------------|---------------| 174 | GRPC API | Stable | 1.0 | [api/](api) | 175 | Metrics API | Stable | 1.0 | - | 176 | Runtime Shim API | Stable | 1.2 | - | 177 | Daemon Config | Stable | 1.0 | - | 178 | Go client API | Unstable | _future_ | [godoc](https://godoc.org/github.com/containerd/containerd) | 179 | CRI GRPC API | Unstable | v1alpha2 _current_ | [api/](https://github.com/kubernetes/kubernetes/tree/master/pkg/kubelet/apis/cri/runtime/v1alpha2) | 180 | `ctr` tool | Unstable | Out of scope | - | 181 182 From the version stated in the above table, that component must adhere to the 183 stability constraints expected in release versions. 184 185 Unless explicitly stated here, components that are called out as unstable or 186 not covered may change in a future minor version. Breaking changes to 187 "unstable" components will be avoided in patch versions. 188 189 ### GRPC API 190 191 The primary product of containerd is the GRPC API. As of the 1.0.0 release, the 192 GRPC API will not have any backwards incompatible changes without a _major_ 193 version jump. 194 195 To ensure compatibility, we have collected the entire GRPC API symbol set into 196 a single file. At each _minor_ release of containerd, we will move the current 197 `next.pb.txt` file to a file named for the minor version, such as `1.0.pb.txt`, 198 enumerating the support services and messages. See [api/](api) for details. 199 200 Note that new services may be added in _minor_ releases. New service methods 201 and new fields on messages may be added if they are optional. 202 203 `*.pb.txt` files are generated at each API release. They prevent unintentional changes 204 to the API by having a diff that the CI can run. These files are not intended to be 205 consumed or used by clients. 206 207 ### Metrics API 208 209 The metrics API that outputs prometheus style metrics will be versioned independently, 210 prefixed with the API version. i.e. `/v1/metrics`, `/v2/metrics`. 211 212 The metrics API version will be incremented when breaking changes are made to the prometheus 213 output. New metrics can be added to the output in a backwards compatible manner without 214 bumping the API version. 215 216 ### Plugins API 217 218 containerd is based on a modular design where plugins are implemented to provide the core functionality. 219 Plugins implemented in tree are supported by the containerd community unless explicitly specified as non-stable. 220 Out of tree plugins are not supported by the containerd maintainers. 221 222 Currently, the Windows runtime and snapshot plugins are not stable and not supported. 223 Please refer to the github milestones for Windows support in a future release. 224 225 #### Error Codes 226 227 Error codes will not change in a patch release, unless a missing error code 228 causes a blocking bug. Error codes of type "unknown" may change to more 229 specific types in the future. Any error code that is not "unknown" that is 230 currently returned by a service will not change without a _major_ release or a 231 new version of the service. 232 233 If you find that an error code that is required by your application is not 234 well-documented in the protobuf service description or tested explicitly, 235 please file and issue and we will clarify. 236 237 #### Opaque Fields 238 239 Unless explicitly stated, the formats of certain fields may not be covered by 240 this guarantee and should be treated opaquely. For example, don't rely on the 241 format details of a URL field unless we explicitly say that the field will 242 follow that format. 243 244 ### Go client API 245 246 The Go client API, documented in 247 [godoc](https://godoc.org/github.com/containerd/containerd), is currently 248 considered unstable. It is recommended to vendor the necessary components to 249 stabilize your project build. Note that because the Go API interfaces with the 250 GRPC API, clients written against a 1.0 Go API should remain compatible with 251 future 1.x series releases. 252 253 We intend to stabilize the API in a future release when more integrations have 254 been carried out. 255 256 Any changes to the API should be detectable at compile time, so upgrading will 257 be a matter of fixing compilation errors and moving from there. 258 259 ### CRI GRPC API 260 261 The CRI (Container Runtime Interface) GRPC API is used by a Kubernetes kubelet 262 to communicate with a container runtime. This interface is used to manage 263 container lifecycles and container images. Currently this API is under 264 development and unstable across Kubernetes releases. Each Kubernetes release 265 only supports a single version of CRI and the CRI plugin only implements a 266 single version of CRI. 267 268 Each _minor_ release will support one version of CRI and at least one version 269 of Kubernetes. Once this API is stable, a _minor_ will be compatible with any 270 version of Kubernetes which supports that version of CRI. 271 272 ### `ctr` tool 273 274 The `ctr` tool provides the ability to introspect and understand the containerd 275 API. It is not considered a primary offering of the project and is unsupported in 276 that sense. While we understand it's value as a debug tool, it may be completely 277 refactored or have breaking changes in _minor_ releases. 278 279 Targeting `ctr` for feature additions reflects a misunderstanding of the containerd 280 architecture. Feature addition should focus on the client Go API and additions to 281 `ctr` may or may not be accepted at the discretion of the maintainers. 282 283 We will do our best to not break compatibility in the tool in _patch_ releases. 284 285 ### Daemon Configuration 286 287 The daemon's configuration file, commonly located in `/etc/containerd/config.toml` 288 is versioned and backwards compatible. The `version` field in the config 289 file specifies the config's version. If no version number is specified inside 290 the config file then it is assumed to be a version 1 config and parsed as such. 291 Use `version = 2` to enable version 2 config. 292 293 ### Not Covered 294 295 As a general rule, anything not mentioned in this document is not covered by 296 the stability guidelines and may change in any release. Explicitly, this 297 pertains to this non-exhaustive list of components: 298 299 - File System layout 300 - Storage formats 301 - Snapshot formats 302 303 Between upgrades of subsequent, _minor_ versions, we may migrate these formats. 304 Any outside processes relying on details of these file system layouts may break 305 in that process. Container root file systems will be maintained on upgrade. 306 307 ### Exceptions 308 309 We may make exceptions in the interest of __security patches__. If a break is 310 required, it will be communicated clearly and the solution will be considered 311 against total impact.