Skip to content

Versioning Policy

Anand Gaitonde edited this page Oct 17, 2018 · 7 revisions

Versioning Policy of the cf CLI

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 feature 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.

Upgrading the cf CLI

When upgrading the cf CLI to a higher patch release, e.g. from 6.35.0 to 6.35.1, 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 the cf CLI to a higher minor release, e.g. from 6.35.1 to 6.36.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 the cf CLI to a higher major release, e.g. from 6.35.1 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 behaviour 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.

Also note that the versioning and policy apply to the cf CLI binaries, not to the installers: It is recommended to download installers from the published URLs or using one of the documented package managers.
Published URLs may redirect requests to URLs that may change over time, so may installer filenames change over time.

Compatibility cf CLI with CF releases/CC API versions

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 aPaaS and products.

As such, every cf CLI release aims to be compatible not only with the latest CF release out at the time the cf CLI is published, but also with every CF version before that.

That said, the cf CLI team does not have the time nor resources to perform compatibility testing with multiple CF releases, so it relies on the CF community to report any issues.
The team does make some effort when refactoring existing commands to go through the published API documentation of older CF releases to confirm APIs were present in previous versions.

Also, over time the amount of branching code to work with both old and new CF releases has been growing, making the code base more and more complex. As branches for older CF releases are not covered in integration testing, it is difficult to safely refactor this code to keep it consistent with the rest of the code.

Hence, with the following considerations, old code branches will be gradually removed:

  • Any expected user impact, e.g. command xxx will stop working on CF <v100, will be documented in the cf CLI release notes;
  • We keep an eye out on what CF versions are still in use out there (mentioned on the CF Dev mailing list, known public CF deployments exposing their CC API version on /v2/info, etc.) and avoid breaking functionality for their users;
  • Our policy for supported versions is that we will support only the current year's certification plus several months' buffer to allow for users to upgrade. See below for additional details.
  • How much effort does it take, vs. what is the current cf CLI team size and workload, to keep supporting code used only to support a feature on an older CF release?

For example, with these considerations, it was decided to remove code branches for CF <v203 from cf CLI 6.24.0 onwards:

  • Release notes of cf CLI 6.23.x have a note at the top with the expected impact of this change in 6.24.0;
  • There have been no questions or issues reported on CF Dev or the cf CLI tracker where users were on CF releases <v203, and all current known public CF PaaS run later versions;
  • CF v203 was published in March 2015, so any CF Certification would have expired by now (CF Certifications expire after a year)
  • The Loggregator team deprecated the Loggregator Consumer library in favor of the Noaa library. The Noaa library only communicates with the Doppler endpoint, deemed reliable from CF v203. The cf CLI team cannot take over support of the deprecated library, hence the need to remove it.

CF CLI Minimum Supported Version

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.

Start of Support Window Minimum CF Deployment/Release Minimum Cloud Controller API Version Minimum CAPI Release
Jan 1, 2018 CF Release v251 2.69.0/3.4.0 1.15.0
Jan 1, 2019 CF Deployment v1.7.0/CF Release v284 2.100.0/3.35.0 1.46.0
You can’t perform that action at this time.