crossplane / crossplane/cli

Define the Crossplane CLI maintenance and docs retention policy

Open
#300 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Go
Stars
19
Forks
31
Avg merge
3d 4h
Merged PRs (30d)
52

Description

### What problem are you facing?

The CLI has no documented maintenance policy. Core Crossplane has one (https://docs.crossplane.io/latest/learn/release-cycle/ quarterly cadence, three most recent minors maintained, roughly nine months per release), but nothing on that page or anywhere else covers the CLI specifically.

This surfaced concretely in a docs PR removing the CLI v2.2 release notes page. Two defensible positions, no rule to decide between them:

- Core v2.2 is still maintained and the v2.2 CLI shipped as part of it, so the docs should stay until core v2.2 is EOL.
- The CLI is now versioned and released independently of core (crossplane/crossplane#7350), so core's support window is the wrong anchor. If we release CLI v2.6 tomorrow with no core release attached, the first rule produces no answer.

crossplane/crossplane#7350 partially covers this: it states that CLI minors are cut for substantial changes and alongside each core minor, and that only the two most recent CLI minors are supported. That PR is still open, lives in c/c rather than here, and addresses CLI-to-core compatibility rather than which CLI versions we maintain and document.

### How could Crossplane help solve your problem?

Land an explicit policy and publish it in the docs. Specifically:

**1. CLI support window.** How many CLI minor versions are maintained, or over what period? Options: two most recent CLI minors (per #7350), three to mirror core, or a time-based window (nine months, as core effectively provides). Whichever we pick needs to hold when the CLI releases off core's cadence.

**2. Patch and backport policy.** Which CLI branches receive backports, and under what criteria. Core's "eligible for backporting to any maintained release branch" is a reasonable starting point.

**3. Docs retention rule.** Which CLI versions keep a docs entry. Proposal: retention follows the CLI support window, with a transitional carve-out for CLI versions that shipped inside core (v2.3 and earlier) those stay until their corresponding core version is EOL. That resolves the v2.2 case without tying future retention to core's cadence.

**4. Compatibility matrix.** A published table of CLI version to supported core versions, derived from the rules in #7350. Today users have to read a design doc to work this out.

**5. Where the policy lives.** Either a section on the existing core release cycle page or a dedicated CLI page under docs.crossplane.io/cli/. The core page is where people will look first, so a CLI section there with a link to fuller detail probably works best.

- crossplane/crossplane#7350 — CLI versioning and release one-pager
- crossplane/crossplane#4850 — CLI separate repository / release cadence
- crossplane/docs#1138 — removal of CLI v2.1 docs during the v2.4 release

Contributor guide

Open the contributing guide

Research direction

Start with the existing core release cycle page and the docs.crossplane.io/cli/ area, then read crossplane/crossplane#7350 and the referenced docs PR history. Done means an agreed CLI support and backport window, a retention rule covering older releases, and a published CLI-to-core compatibility matrix with the policy linked from the core release documentation.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, release
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.