kubernetes-sigs/kustomize
1
0
Fork 0
mirror of https://github.com/kubernetes-sigs/kustomize.git synced 2026-06-14 10:30:59 +00:00
Code Issues Packages Projects Releases 1 Wiki Activity

Merge pull request #2763 from monopole/updateReleaseInstructions

Browse Source 
Update release instructions.
This commit is contained in:
Jeff Regan
2020-07-24 10:28:55 -07:00
committed by GitHub
parent a0fdcfe2e3 d437f67035
commit 1dff481883
1 changed files with 147 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
releasing/README.md
View File

@@ -6,161 +6,150 @@
[semver]: https://semver.org [semver]: https://semver.org
[Go modules]: https://github.com/golang/go/wiki/Modules [Go modules]: https://github.com/golang/go/wiki/Modules
[multi-module repo]: https://github.com/go-modules-by-example/index/blob/master/009_submodules/README.md [multi-module repo]: https://github.com/go-modules-by-example/index/blob/master/009_submodules/README.md
[semver review]: #semver-review
[semver release]: #semver-review
[`cloudbuild.yaml`]: cloudbuild.yaml
This document describes how to perform a [semver] release This document describes how to perform a [semver release]
of one of the [Go modules] in this repository. of one of the [Go modules] in this repository.
These modules release independently. Briefly:
- The repo HEAD is in a clean state (all tests passing).
- A specially formatted tag is applied to the repo and pushed upstream
(on minor or major revisions there will also be a new branch).
- A tag trigger in [Google Cloud Build], reading instructions from
[`cloudbuild.yaml`] in this directory, creates release artifacts
as needed and makes them available on the [release page].
See this [multi-module repo] tagging discussion ## Public Modules
for an explanation of the `foo/v2.3.0` tags applied below.
## Module summaries TODO: _This list is incomplete._
[`sigs.k8s.io/kustomize/kustomize`]: #sigsk8siokustomizekustomize [`sigs.k8s.io/kustomize/kustomize`]: #sigsk8siokustomizekustomize
[`sigs.k8s.io/kustomize/api`]: #sigsk8siokustomizeapi [`sigs.k8s.io/kustomize/api`]: #sigsk8siokustomizeapi
[`sigs.k8s.io/kustomize/pluginator`]: #sigsk8siokustomizepluginator [`sigs.k8s.io/kustomize/kustomize`]: #sigsk8siokustomizekustomize
[`sigs.k8s.io/kustomize/kyaml`]: #sigsk8siokustomizekyaml
[`sigs.k8s.io/kustomize/cmd/config`]: #sigsk8siokustomizecmdconfig
[kustomize/v3.2.1]: /../../releases/tag/kustomize%2Fv3.2.1 [kustomize/v3.2.1]: /../../releases/tag/kustomize%2Fv3.2.1
[pluginator/v1.0.0]: /../../releases/tag/pluginator%2Fv1.0.0 [pluginator/v1.0.0]: /../../releases/tag/pluginator%2Fv1.0.0
| Module Description | Module Prefix | Ex. Tag | Ex. Branch Name | | Module Name | Module Description | Example Tag | Example Branch Name |
| --- | ------ | --- | --- | | ------ | --- | --- | --- |
| kustomize executable | [`sigs.k8s.io/kustomize/kustomize`] | _kustomize/v3.2.2_ | _release-kustomize-v3.2.2_ | | [`sigs.k8s.io/kustomize/kustomize`] | kustomize executable | _kustomize/v3.2.2_ | _release-kustomize-v3.2.2_ |
| kustomize Go API | [`sigs.k8s.io/kustomize/api`] | _api/v0.1.0_ | _release-api-v0.1_ | | [`sigs.k8s.io/kustomize/api`] | kustomize API | _api/v0.1.0_ | _release-api-v0.1_ |
| pluginator executable | [`sigs.k8s.io/kustomize/pluginator`] | _pluginator/v1.0.0_ | _release-pluginator-v1.0_ | | [`sigs.k8s.io/kustomize/kyaml`] | k8s-specific yaml editting | _kyaml/v0.3.3_ | _release-kyaml-v0.2_ |
| [`sigs.k8s.io/kustomize/cmd/config`] | kyaml related commands | _cmd/config/v0.3.3_ | _release-cmd/config-v0.3_ |
### sigs.k8s.io/kustomize/kustomize > ### sigs.k8s.io/kustomize/kustomize
>
> The `kustomize` program, a CLI for performing
> structured edits to Kubernetes Resource Model (KRM) YAML.
>
> There's only one public package in this module.
> It's called `main`, it's therefore unimportable.
> It holds the `kustomize` executable.
>
> See the [installation instructions](../docs/INSTALL.md)
> to perform an install.
>
>
> ### sigs.k8s.io/kustomize/api
>
> The [kustomize Go API](https://github.com/kubernetes-sigs/kustomize/tree/master/api).
>
> The packages in this module are used by API clients,
> like the `kustomize` program itself, and programs in
> other repositories, e.g. `kubectl`. They include
> methods to read, edit and emit modified YAML.
>
> Release notes should appear on the [release page].
>
> The package has a toy executable called `api`, which,
> if run, prints the API release version, but has no
> other use.
>
> ### sigs.k8s.io/kustomize/kyaml
>
> The [kyaml module](https://github.com/kubernetes-sigs/kustomize/tree/master/kyaml).
>
> Low level packages for transforming YAML associated
> with KRM objects.
>
> These are used to build _kyaml filters_, computational units
> that accept and emit KRM YAML, editing or simply validating it.
>
> The kustomize `api` and the `cmd/config` packages are built on this.
>
> ### sigs.k8s.io/kustomize/cmd/config
>
> The [cmd/config module](https://github.com/kubernetes-sigs/kustomize/tree/master/cmd/config).
>
> A collection od CLI commands that correspond to
> kyaml filters.
>
> ### sigs.k8s.io/kustomize/pluginator
>
> The `pluginator` program, a code generator that
> converts Go plugins to conventional statically
> linkable library code.
>
> Only holds a `main`, and therefore unimportable.
> It holds the _pluginator_ executable.
>
> This binary is only of
> interest to someone writing a new builtin
> transformer or generator. See the [plugin
> documentation](../docs/plugins).
> Its dependence on the API is for
> plugin-related constants, not logic.
The `kustomize` program, a CLI for performing ## Release a module
k8s-aware structured edits to YAML in k8s resource
files.
#### Packages In this repo, releasing a module is accomplished by applying
a tag to the repo and pushing it upstream. A minor release
branch is also created as necessary to track patch releases.
There's only one public package in this module. A properly formatted tag (described below) contains
It's called `main`, it's therefore unimportable, the module name and version.
and it holds the _kustomize_ executable.
Pushing the tag upstream will trigger [Google Cloud Build] to build a release
and make it available on the [release page].
#### Release artifacts Cloud build reads its instructions from the
[`cloudbuild.yaml`] file in this directory.
Executable files appear for various operating We use a Go program to make the tagging and branch
systems on the [release page]. The tag creation process less error prone.
appears in the URL, e.g. [kustomize/v3.2.1].
See the [installation instructions](../docs/INSTALL.md) ### List the latest tags
to perform an install.
### sigs.k8s.io/kustomize/api
This is the kustomize Go API.
#### Packages
The packages in this module are used by API clients,
like the `kustomize` program itself, and programs
in other repositories, e.g. `kubectl`.
They include methods to read, edit and emit
modified YAML.
Go consumers of this API will have a `go.mod` file
requiring this module at a particular tag, e.g.
```
require sigs.k8s.io/kustomize/api v0.1.0
```
#### Release artifacts
This is a Go library-only release, so the only
artifact per se is the repo tag, in the form `api/v1.2.3`,
that API clients can `require` from their `go.mod` file.
Release notes should appear on the [release page].
There's a toy executable called `api`, which, if
run, prints the API release provenance data, but it's of
no practical use to an API client.
### sigs.k8s.io/kustomize/pluginator
The `pluginator` program, a code generator that
converts Go plugins to conventional statically
linkable library code.
#### Packages
There's only one package in this module.
It's called `main`, it's therefore unimportable,
and it holds the _pluginator_ executable.
At the time of writing this binary is only of
interest to someone writing a new builtin
transformer or generator. See the [plugin
documentation](../docs/plugins).
Its dependence on the API is primarily for
plugin-related constants, not logic, and will
only change if there's some change in how
plugins are constructed (presumably
infrequently).
#### Release artifacts
Executables appear on the [release page].
The tag appears in the URL, e.g. [pluginator/v1.0.0].
## Releasing Program
The Go program used to release modules is in `releasing/releasing` directory.
### List current module versions
```bash ```bash
(cd releasing/releasing; go run . list) (cd releasing/releasing; go run . list)
``` ```
This command will print the latest versions of supported modules. Example output (this shows properly formatted tags):
Example output:
``` ```
kyaml/v0.3.0
api/v0.4.1 api/v0.4.1
cmd/config/v0.3.0 cmd/config/v0.3.0
cmd/resource/v0.0.2 cmd/resource/v0.0.2
cmd/kubectl/v0.1.0 cmd/kubectl/v0.1.0
pluginator/v2.1.0 kyaml/v0.3.0
kustomize/v3.6.1 kustomize/v3.6.1
pluginator/v2.1.0
``` ```
### Releasing a module See this [multi-module repo] tagging discussion
for an explanation of the path-like portion of these tags.
To release a module, you need to make sure that: ### Release
- The codes in the module are ready to release, i.e. pass all tests and It's assumed that whatever is already commited to the latest
release check. This program will not do any code verification. commit is passing all tests and appropriate for release.
Command: Get up to date:
```bash
(cd releasing/releasing; go run . release {moduleName} {versionField})
```
The command only accepts 3 version types: major, minor or patch.
The specified version will be increased by 1 and inferior version(s) will be reset to 0.
By default the `release` command will not create release in the remote
unless you add a `--no-dry-run` flag. You can check the output of the dry-run command to ensure the behavior is expected.
## Release procedure
The previous release program does most of the following steps create a
release.
At any given moment, the repository's master branch is
passing all its tests and contains code one could release.
### get up to date
``` ```
git fetch upstream git fetch upstream
@@ -168,10 +157,40 @@ git checkout master
git rebase upstream/master git rebase upstream/master
``` ```
Then:
```
(cd releasing/releasing; go run . release {moduleName} {versionField})
```
Where
* `{moduleName}` must be `kyaml`, `kustomize`, `cmd/config`, etc.
* `{versionField}` must be `major`, `minor` or `patch` (see [semver review] below).
The specified version will be incremented, and
inferior version(s) will be set to zero.
E.g. if the current version is `v3.4.1`, incrementing `minor`
results in `v3.5.0`.
This program only applies a tag, and pushes it upstream.
To make this actually happen, add the `--no-dry-run` flag
to the `release` command.
### update release notes
Visit the [release page] and edit the release notes as desired.
## Manual process
The release program does the following for you.
### select a module to release ### select a module to release
``` ```
module=pluginator # The pluginator executable
module=kustomize # The kustomize executable module=kustomize # The kustomize executable
module=api # The API module=api # The API
``` ```
@@ -188,7 +207,13 @@ Remote:
git ls-remote --tags upstream | grep $module git ls-remote --tags upstream | grep $module
``` ```
### determine the version Set the version you want:
```
major=0; minor=1; patch=0
```
#### semver review
Go's [semver]-compatible version tags take the form `v{major}.{minor}.{patch}`: Go's [semver]-compatible version tags take the form `v{major}.{minor}.{patch}`:
@@ -202,9 +227,7 @@ Go's [semver]-compatible version tags take the form `v{major}.{minor}.{patch}`:
- If there's an API change (either the Go API or the CLI behavior - If there's an API change (either the Go API or the CLI behavior
with respect to CLI arguments and flags), increment `major`. with respect to CLI arguments and flags), increment `major`.
```
major=0; minor=1; patch=0
```
### create the release branch ### create the release branch
@@ -331,8 +354,7 @@ git push upstream latest_kustomize
git remote set-url --push upstream no_push git remote set-url --push upstream no_push
``` ```
This triggers a job in [Google Cloud Build] to This triggers [Google Cloud Build].
put a new release on the [release page].
### update release notes ### update release notes