-
Notifications
You must be signed in to change notification settings - Fork 932
Versioning and Support Policy
The cf CLI uses semantic versioning to give its users an idea of what to expect when upgrading, how much effort one can expect to need to put in investigating whether an upgrade could break scripts, accustomed workflows, written notes and instructions.
It offers confidence that commands and features do not disappear between releases unexpectedly.
The cf CLI's version format follows SemVer 2.0.
The SemVer specification defines a number of rules based around a defined "public API" of a package, with the purpose of dealing with dependency upgrades.
In the case of the cf CLI, these rules should be interpreted in relation to the commands and their syntax and behaviour.
There is no interface supported for public use in the code base.
The following sections discuss the impact of this policy in more detail.
-
When upgrading to a new patch release (e.g. from 7.0.1 to 7.0.2)...
one can expect the new release to primarily consist of bug fixes. It may also include improvements to help, flavor text, trace output and translations, but no new commands or options. Also, the information returned when running a command on different patch releases against the same API endpoint should not change, e.g. no columns in a table added or removed.
-
When upgrading to a new minor release (e.g. from 7.0.2 to 7.1.0)...
one can expect new features, including new commands and options, in addition to bug fixes and other changes expected in patch releases.
-
When upgrading to a new major release (e.g. from 6.52.0 to 7.0.0)...
one can expect major feature changes, including removal of deprecated commands, new workflows and other changes that likely would break existing scripts and plugins.
Note that this policy does not offer protection against unintended changes in behavior in releases that could cause regressions even in upgrades to patch releases. However, such regressions will be treated with priority and considered for resolution in the first upcoming release, or even cause an additional patch release to be scheduled ahead of the originally planned subsequent release.
Also, the cf CLI depends on certain features provided by its implementation language Golang and its tooling, such as support for multiple platforms and operating systems. Due to occasional security vulnerability patches for Golang, the cf CLI is generally built with the latest (patch release) version of Golang. If Golang stops supporting certain platforms or operating systems, e.g. Windows Vista or 32 bit because it reached its vendor's general "End of Life", the cf CLI will also stop supporting that platform. This will not be considered a change that requires a major version bump, even if the cf CLI completely stops working: most users will not be affected by this anyway, and any users still on such platforms should be migrating anyway - a major version bump would cause alarm and confusion among users of supported platforms who would worry they would be affected as well.
The table below goes into more details about changes that you might expect, not every release will contain every single change listed below (Please refer to release notes for changes included in each release.); the intent is to codify changes for each release version so that users know what to expect, and so that contributors to the cf CLI adhere to this versioning policy.
| Type | Patch Release | Minor Release | Major Release | Notes |
|---|---|---|---|---|
| Arguments Options | No removal or new required arg | No removal or new required arg | ||
| Bugs | Bug fixes | Bug fixes | Bug fixes | |
| Config | Backwards compatible updates | Backwards compatible updates | As long as functionality is backwards compatible (older versions (within in our support window) of the config works as expected), we reserve the right to remove/edit properties in the config in patch and minor releases. The config is not a public interface. | |
| Commands | No removal of commands | No removal of commands | ||
| Command Output | Changes to command output | Changes to command output | Changes to command output | Command output has changed in many 6.x.x releases. In v7 CLI some output is no longer controlled by the cf CLI (we return the CC API response). Therefore, output is subject to change in any release. |
| CVE | CVE fixes | CVE fixes | CVE fixes | |
| Golang updates | Change Golang version if there is a Golang-related issue | Update to a minor or major version of Golang | Update to a minor or major version of Golang | Major versions of Golang may contain changes to operating system support. See the Support for Operating Systems below, and our Upgrading Section for more information regarding alignment with Golang's supported platforms and operating systems. |
| Deprecation | Adds deprecation warnings | Adds deprecation warnings | Removal of deprecated commands and features | |
| Exit Codes | Changes only if a bug is found | Changes only if a bug is found | In v7, idempotent commands will exit 0. Once v7 GAs, changes in exit codes will be rare and changed only if a bug is found. If this occurs, we will of course document it in release notes. |
|
| Features | New features - additive only (e.g new commands or backwards compatible flag options) | New features (e.g new commands or flag options) | ||
| Flag Options | No removal of flag options | No removal of flag options | ||
| Flavor Text | Flavor text updates | Flavor text updates | Flavor text updates | |
| Help Text | Help text updates | Help text updates | Help text updates | |
| Key/Value | No changes to key/value display | Additive-only changes to key/value display | Removal of key/value items | |
| Operating System Support | Tied to Golang's Support for OS | Tied to Golang's Support for OS | If Golang stops supporting certain platforms or operating systems, e.g. Windows Vista or 32 bit because it reached its vendor's general "End of Life", the cf CLI will also stop supporting that platform. We will notify the Community before we upgrade a major version of Golang which contains OS support changes. | |
| Table Display | No changes to table display | Additive-only changes to table display | Removal of table items | In minor releases, we will endeavor not to change column order. New columns will be added to the last column. |
| Trace Output | Trace output changes | Trace output changes | Trace output changes | |
| Translations | Translation updates | Translation updates | Translation updates | |
| Versioning | Backwards Compatibility in concert with our Versioning Policy | Backwards Compatibility in concert with our Versioning Policy |
It is the cf CLI team’s aim to deliver a CLI that can be used by all Cloud Foundry users; a single tool to talk to all your Cloud Foundry deployments. This includes your local bosh-lite deployments as well as your production, commercial and possibly multi-region Cloud Foundry based PaaS and products.
Our aim is to provide a cf CLI release compatible with every version of CF deployment greater than or equal to v7.0.0. See the Readme for more information on versioning.
In order to focus our resources on the most valuable features and bug fixes, the CF CLI team periodically announces the end of support for older Cloud Controller (CC) API versions. See the table below for the currently supported minimum.
Going forward, we want to give users a more predictable annual cycle for cf CLI version support cut-offs so you can plan accordingly. We also want to tighten up this timeline so the CF CLI team can narrow its focus to fewer CC API versions without unduly disrupting your use of CF.
To this end, CF CLI will only maintain support as far back as the previous year’s CF Certification, and we've also add additional cushion to enable a more seamless upgrade process. Older CF CLI versions compatible with older CF releases will continue to be available. However, upon the new year, the first CLI release of that year will remove all code pertaining to unsupported releases.
| CLI Major Version | Start of Support Window | Min CF Deployment | Min Cloud Controller API Versions | Min CAPI Release | Max CF Deployment | Max Cloud Controller API Versions | Max CAPI Release |
|---|---|---|---|---|---|---|---|
| V6 | Jan 1, 2020 | v7.0.0 | 2.128.0/3.63.0 | 1.74.0 | v13.4.0 | 2.149.0/3.84.0 | v1.94.0 |
| V7 | June 25, 2020 | v13.5.0 | 2.150.0/3.85.0 | 1.95.0 | Latest | Latest | Latest |