kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-05-25 16:18:37 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Merge pull request #1247 from monopole/updateReleaseNotes

Browse Source 
Update versioning policy.
This commit is contained in:
Jeff Regan
2019-06-24 17:27:44 -07:00
committed by GitHub
parent b0f59358d9 7a67645558
commit bc31fa9120
2 changed files with 78 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
docs/v3.0.0.md
View File

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

29
docs/versioningPolicy.md
View File

@@ -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):