diff --git a/docs/v3.0.0.md b/docs/v3.0.0.md index 04c112b35..68c74f80a 100644 --- a/docs/v3.0.0.md +++ b/docs/v3.0.0.md @@ -1,55 +1,72 @@ # kustomize 3.0.0 -This release is basically [v2.1.0](v2.1.0.md), with some -post-v2.1.0 bugs fixed and a `v3` in Go package -paths. +This release is basically [v2.1.0](v2.1.0.md), +with some post-v2.1.0 bugs fixed and a `v3` in Go +package paths. [plugin]: https://github.com/kubernetes-sigs/kustomize/tree/master/docs/plugins -The major version increment to `v3` begins a new API -that puts [plugin] developers (both _Go_ plugin -developers and _exec_ plugin developers who happen to -use Go) on a solid footing through the coming -series of minor releases and patches. +The major version increment to `v3` puts a new +floor on a stable API for [plugin] developers +(both _Go_ plugin developers and _exec_ plugin +developers who happen to use Go), to carry them +through the coming series of minor releases and +patches. -### Go Module implications +### Why so soon after v2.1.0? -[doc]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher +[semantic versioning]: https://semver.org +[Go modules doc]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher +[versioning policy]: versioningPolicy.md -Per the Go modules [doc], a release that's already -tagged v2 or higher should increment the major -version when performing their first Go +We made a mistake - v2.1.0 should have been +v3.0.0. Per the [Go modules doc] (which have +improved a great deal recently), a release that's +already tagged v2 or higher should increment the +major version when performing their first Go module-based release. This advice applies to kustomize, since it was -already at major version 2 when switching to Go -modules. +already at major version 2 when it began using Go +modules to state _its own_ dependencies in v2.1.0. -[versioning policy]: versioningPolicy.md +But the more important reason for `v3` is a change +to the kustomize [versioning policy], forced by +the introduction of plugins. -The other reason for `v3` is that the `go` tool -assumes Go modules obey semantic versioning, which -means packages used in v2.1 should have the same -API as packages in v2.0. +Historically, kustomize's [versioning policy] +didn't involve Go modules and addressed _only_ the +command line tool's behavior and the fields in a +kustomization file. The underlying packages were +an implementation detail, not under semantic +versioning, because they weren't intended for +export (and should have all been under +`internal`). Thus although the v2.1.0 CLI is +backward compatible with v2.0.3, the underlying +package APIs are not. -This is not the case in kustomize. Historically, -kustomize's [versioning policy] has only addressed -the command line tool's behavior and the fields in -a kustomization file. The underlying packages -were an implementation detail, avaiable for use at -the author's risk. - -With the introduction of plugins, the packages - -in particular `loader` and `resmap` - become part -of an API formally exposed to plugin authors, so -the API changes must be respected. - -Over time, _informed by package use_, the API -surface should shrink, but such shrinkage will -require a major version increment. +[minimal version selection]: https://research.swtch.com/vgo-mvs +With Go modules, the `go` tool must assume that Go +packages respect [semantic versioning], so it can +perform [minimal version selection]. +With the introduction of alpha plugins, kustomize +sub-packages - in particular `loader` and +`resmap` - become part of an API formally exposed +to plugin authors, and so must be semantically +versioned. This allows plugins defined in other +repositories to clarify that they depend on +kustomize v3.0.0, and not see confusing errors +arising from incompatibilities between v2.1.0 and +v2.0.3. Hence, the jump to v3. + +Aside - the set of kustomize packages outside +`internal` is too large, and over time, informed +by package use, this API surface must shrink. +Such shrinkage will trigger a major version +increment. diff --git a/docs/versioningPolicy.md b/docs/versioningPolicy.md index 278348b30..73a50645b 100644 --- a/docs/versioningPolicy.md +++ b/docs/versioningPolicy.md @@ -1,13 +1,15 @@ # Versioning Running `kustomize` means one is running a -particular version of a program, reading a -particular version of a [kustomization] file. +particular version of a program, using a +particular version of underlying packages, and +reading a particular version of a [kustomization] +file. ## Program Versioning The command `kustomize version` prints a three -field version tag (e.g. `1.0.11`) that aspires to +field version tag (e.g. `v3.0.0`) that aspires to [semantic versioning]. When enough changes have accumulated to @@ -15,6 +17,27 @@ warrant a new release, a [release process] is followed, and the fields in the version number are bumped per semver. +## Kustomize packages + +At the time of writing, the kustomize program and +the packages it uses (and exports) are in the same +Go module (see the top level `go.mod` file in the +repo). + +[trailing major version indicator]: https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher + +Thus, they share the module's version number, per +its git tag (e.g. `v3.0.0`), whose major verion +number matches the [trailing major version +indicator] in the module name (e.g. the `/v3` in +`sigs.k8s.io/kustomize/v3`). + +The non-internal packages in the Go module +`sigs.k8s.io/kustomize/v3`, introduced in +[v3.0.0](v3.0.0.md), conform to [semantic +versioning]. + + ## Kustomization File Versioning At the time of writing (circa release of v2.0.0):