1# Cosign Versioning Policy
2
3This is the versioning policy regarding the stability of Cosign, both the API and CLI.
4
5**tl;dr (CLI):** semver for specific behaviors, but with deprecations.
6
7**tl;dr (API):** no guarantees at all (for now).
8
9Principles:
10
11- Provide well-versioned, very reliable tools/libraries that people can write
12 scripts/code against.
13- Provide places for experimentation and rapid-development, not covered under
14 versioning guarantees.
15- Be explicit about what is and isn’t covered.
16- Better to promise a weaker guarantee and stick to it consistently than to be
17 vague about what is/isn’t covered and technically comply, or not comply at
18 all.
19
20## Cosign CLI
21
22The Cosign CLI’s version numbers are of the form `MAJOR.MINOR.PATCH`, but it is
23explicitly not covered by [semantic versioning][semver] guarantees. Instead, you
24should interpret version numbers as follows:
25
26**Major version increases.** These are "large changes." You should expect to
27need to rewrite scripts after these. There are no compatibility guarantees about
28the behavior or shape of the CLI. These should be infrequent and correspond to
29big improvements in the user experience.
30
31**Minor version increases.** These are "small changes." If you’ve been paying
32attention to and fixing deprecation warnings (see
33["Deprecation"](#deprecation)), your scripts should continue to work (provided
34they only depend on explicitly guaranteed Cosign behavior; see "What's
35covered?").
36
37**Patch version increases.** These are "bug fix" releases only, and should
38always be adopted..
39
40[semver]: https://semver.org
41
42### What's covered?
43
44Only behavior explicitly listed here is covered (to counter [Hyrum's
45Law][hyrums-law]).
46
47* Any documented behavior (i.e., behavior described in the output of `cosign -h`).
48 If the wording is ambiguous, the behavior may change as long as the
49 corresponding documentation changes to make it less ambiguous.
50* Output to standard output, *when described in the documentation*. Each command
51 should describe its default output format (ideally with examples).
52 * Any scripts should *only* rely on standard output.
53 * Consumers using compliant parsers will continue to be able parse the output of Cosign.
54 * New fields may be added, but fields will not be removed.
55* Additional conventions documented in [CLI.md](CLI.md).
56
57What’s *not* covered?
58
59* Output to standard error is *not* covered and may change at any time.
60* If the Sigstore API changes, the output of Cosign may change.
61* Fixes to security bugs (for instance, something invalid used to pass
62 verification, but now it does not). However, "security features" should not
63 break backwards-compatibility.
64* Any "unstable" commands.
65
66Violations of this are generally considered bugs; we will issue patch releases
67for each affected minor version. In some (rare) cases, an exception may be made
68with the approval of the Cosign maintainers as long as the decision results in
69an update to this versioning policy.
70
71[hyrums-law]: https://www.hyrumslaw.com/
72
73### Feature stability
74
75It’s important to enable rapid iteration on the development of new Cosign
76features while providing stability to users of more-mature features. As such,
77the Cosign CLI will support the following release levels with corresponding
78guarantees:
79
80* **Experimental**: No guarantees. May change in a backwards-incompatible way or
81 be removed at any time without warning.
82* Generally available (**GA**): follows the guidelines in this document.
83
84Users must explicitly indicate that they want to opt-in to experimental behavior
85by setting the environment variable `COSIGN_EXPERIMENTAL=1`.
86
87### Supported versions
88
89**Full support.** We fully support only the latest release of the Cosign CLI.
90
91**Security support.** We will backport security fixes to all major versions
92released in the past year. We may backport security fixes, depending on
93severity, to all minor versions released in the last year. We may choose to
94backport security "features" as well.
95
96### Deprecation
97
98Any behavior may be deprecated at any time with sufficient warning. For GA
99features, that period is 6 months from the Cosign release in which the
100deprecation was first announced; the first subsequent Cosign release should
101remove that feature. A new major version voids all deprecation timeline
102guarantees, and any deprecated behaviors can be removed at that time.
103
104Deprecation requires:
105
106* When users invoke the deprecated behavior, print a deprecation message to
107 standard error.
108 * The message should look something like:
109 ```
110 WARNING: $BEHAVIOR is deprecated and will be removed in a Cosign release
111 soon after $DEPRECATION_DATE (see $GITHUB_ISSUE_LINK). Instead, please
112 $ALTERNATIVE.
113 ```
114 * If we can’t tell whether a user is using the deprecated behavior (for
115 instance, if we’re going to remove a field), print the message every time.
116 * There MAY be a way to turn off the message. In many cases, this will just be
117 by using the alternative. Otherwise, we can consider adding a flag (which is
118 now subject to a deprecation period of its own).
119* A release note at the introduction of the deprecation, along with the removal
120 of the behavior.
121* Any documentation that refers to the deprecated behavior in the Cosign
122 repository should have the same information as in the message.
123 * Other documentation will be updated on a best-effort basis.
124
125For a list of currently deprecated behavior, search the codebase (all deprecated
126behavior will use a shared "deprecation" library and therefore be easy to find).
127
128### Rationale/background
129
130Currently, many folks assume that the Cosign CLI follows semantic versioning. We
131have a bunch of breaking changes blocked on a 2.0 release. Even after that
132point, there are a number of proposed breaking changes/overhauls proposed. But
133there’s hesitancy to publish another major version. Further, semver doesn’t lend
134itself to a regular deprecation train (marking things deprecated, then ripping
135out after a fixed period of time); rather, in semver, you always have to wait
136for a new major version, which batches together a bunch of proposed deprecated
137behavior.
138
139Approaches considered include:
140
141* Follow semver. Bump major versions frequently (this is why Chrome is at
142 version 107 and Firefox is at 106, and gcloud is at version 409). I think this
143 is actually way more user-hostile; it effectively means "there are no
144 compatibility guarantees."
145* Follow semver. Avoid major version releases. I think that Sigstore and Cosign
146 are developing too rapidly to commit to avoid breaking things. Further, this
147 winds up preventing incremental improvements to the CLI in favor of huge
148 changes. For instance, right now with the v2 work underway the codebase is in
149 an awkward spot and would take a fair bit of work/branch management to push a
150 minor version release; realistically, the next release will be v2 even if we
151 have bug fixes we could push before then.
152
153## API support for old Cosign versions
154
155Starting with Cosign CLI v2, the Sigstore infrastructure should support old
156Cosign versions for one year past release, and six months past the availability
157of a suitable replacement. Any breakage here will be considered a bug and should
158be rolled back or fixed.
159
160We will run end-to-end tests for all prior supported minor versions.
161
162## Cosign API
163
164The Cosign API is versioned independently of the Cosign CLI. Version numbers are
165`MAJOR.MINOR.PATCH`. For now, there are **no stability guarantees**:
166
167* The library will undergo a serious refactor to make using it much
168 safer/easier.
169* Most callers (anybody not dealing with OCI registries/containers) will want
170 [sigstore-go][] instead.
171* At a future major version, the library will follow semantic versioning (and
172 this policy will be updated).
173* After that point, only code in pkg/ will be covered by semver; Cosign will
174 follow semver strictly.
175 * Functionality should be private (either language-private or in a "private"
176 package like `internal/` or `cmd/`) by default, and exposing it publicly
177 will be a deliberate choice.
178 * In-development features will live under a new `pkg/experimental/` directory,
179 which will not be covered by semver.
180 * Updating a library is safer than updating a CLI tool, so we will bump major
181 versions liberally (though not excessively).
182
183### Rationale/background
184
185We are not currently maintaining the Cosign API as if it’s a 1.0 library. There
186are breaking changes all the time, and contributors don’t even seem to notice
187(users might, but they haven’t complained much)! So effectively it's got no
188versioning policy as-is; this just makes that official.
189
190The only reason it’s marked 1.0 is because the CLI was marked 1.0; it certainly
191isn’t ready for semver guarantees ([which Golang requires][go-semver]). Also, it
192doesn’t make sense to tie the versions of the API and CLI to each other. If I
193wanted to do a big refactor of the API that didn't affect the CLI, that might
194require a major version bump even if the CLI was entirely unchanged.
195
196Soon, [sigstore-go][] will be the default Golang API for Sigstore; this library
197will have a well-thought-out API and be stable. After that point, we can
198refactor Cosign to use it (see [Sigstore in Golang][sigstore-in-golang]) and
199then clean up the Cosign API for those who need OCI support.
200
201[go-semver]: https://go.dev/doc/modules/release-workflow#breaking
202[sigstore-go]: https://github.com/sigstore/sigstore-go
203[sigstore-in-golang]: https://docs.google.com/document/d/1aZfk1TlzcuaO0uz76M9D26-gAvoZLn0oCAKvkbuhcPM/edit
View as plain text