Skip to content

Commit 3e3e14a

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #1201 from puerco/krel-documentation
First compilation of krel documentation
2 parents f4a82e7 + d283cf8 commit 3e3e14a

File tree

7 files changed

+305
-5
lines changed

7 files changed

+305
-5
lines changed

‎docs/krel/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# krel — The Kubernetes Release Toolbox
2+
3+
`krel` is the new golang based tool for managing releases.
4+
5+
- [Summary](#summary)
6+
- [Installation](#installation)
7+
- [Usage](#usage)
8+
- [Important notes](#important-notes)
9+
10+
## Summary
11+
The purpose of krel is to provide a toolkit for managing the different steps needed to create
12+
Kubernetes Releases. This includes manually executed tasks like generating the Release Notes during the release cycle and performing automated tasks like pushing the Kubernetes release artifacts to Google Cloud Storage.
13+
14+
## Installation
15+
Compile krel by running the `compile-release-tools` run from the root of this repo:
16+
17+
```shell
18+
./compile-release-tools krel
19+
```
20+
21+
## Usage:
22+
krel has several subcommands that perform various tasks during the release lifecycle:
23+
24+
```krel [subcommand]```
25+
26+
### Available Commands:
27+
| Subcommand | Description |
28+
| --- | --- |
29+
| [changelog](changelog.md) | Automate the lifecycle of CHANGELOG-x.y.{md,html} files in a k/k repository |
30+
| [ff](ff.md) | Fast forward a Kubernetes release branch |
31+
| [gcbmgr](gcbmgr.md) | Submit Kubernetes staging and release jobs to Google Cloud Build |
32+
| [patch-announce](patch-announce.md) | Send out patch release announcement mails |
33+
| [push](push.md) | Push Kubernetes release artifacts to Google Cloud Storage (GCS) |
34+
| [release-notes](release-notes.md) | The subcommand of choice for the Release Notes subteam of SIG Release |
35+
36+
## Important Notes
37+
38+
Some of the krel subcommands are under development and their usage may already differ from these docs.

‎docs/krel/changelog.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# krel changelog
2+
Automate the lifecycle of CHANGELOG-x.y.{md,html} files in a k/k repository
3+
4+
- [Summary](#summary)
5+
- [Installation](#installation)
6+
- [Usage](#usage)
7+
- [Important notes](#important-notes)
8+
9+
## Summary
10+
The `changelog` subcommand of `krel` does the following things by utilizing
11+
the golang based `release-notes` tool:
12+
13+
1. Generate the release notes for either a patch or a new minor release. Minor
14+
releases can be alpha, beta or rc’s, too.
15+
16+
a) Create a new `CHANGELOG-x.y.md` file if not existing.
17+
18+
b) Correctly prepend the generated notes to the existing `CHANGELOG-x.y.md`
19+
file if already existing. This also includes the modification of the
20+
table of contents.
21+
22+
2. Convert the markdown release notes into a HTML equivalent on purpose of
23+
sending it by mail to the announce list. The HTML file will be dropped into
24+
the current working directly as `CHANGELOG-x.y.html`. Sending the
25+
announcement is done by another subcommand of 'krel', not 'changelog'.
26+
27+
3. Commit the modified CHANGELOG-x.y.md` into the master branch as well as the
28+
corresponding release-branch of kubernetes/kubernetes. The release branch
29+
will be pruned from all other CHANGELOG-*.md files which do not belong to
30+
this release branch.
31+
32+
## Installation
33+
34+
Simply [install krel](README.md#installation).
35+
36+
## Usage
37+
```
38+
krel changelog [flags]
39+
```
40+
### Command Line Flags
41+
```
42+
Flags:
43+
--branch string The branch to be used. Will be automatically inherited by the tag if not set.
44+
--bucket string Specify gs bucket to point to in generated notes (default "kubernetes-release")
45+
-h, --help help for changelog
46+
--html-file string The target html file to be written. If empty, then it will be CHANGELOG-x.y.html in the current path.
47+
--record string Record the API into a directory
48+
--replay string Replay a previously recorded API from a directory
49+
--tag string The version tag of the release, for example v1.17.0-rc.1
50+
--tars string Directory of tars to SHA512 sum for display (default ".")
51+
```
52+
53+

‎docs/krel/ff.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# krel ff
2+
Fast forward a Kubernetes release branch
3+
4+
- [Summary](#summary)
5+
- [Installation](#installation)
6+
- [Usage](#usage)
7+
- [Important notes](#important-notes)
8+
9+
## Summary
10+
`ff` fast forwards a branch to a specified git object (defaults to origin/master).
11+
12+
`krel ff` pre-checks that the local branch to be forwarded is an actual
13+
'release-x.y' branch and that the branch exists remotely. If that is not the
14+
case, `krel ff` will fail.
15+
16+
After that preflight-check, the release branch will be checked out and krel
17+
verifies that the latest merge base tag is the same for the master and the
18+
release branch. This means that only the latest release branch can be fast
19+
forwarded.
20+
21+
krel merges the provided ref into the release branch and asks for a final
22+
confirmation if the push should really happen. The push will only be executed
23+
as real push if the `--nomock` flag is specified.
24+
25+
## Installation
26+
Simply [install krel](README.md#installation).
27+
28+
## Usage
29+
```
30+
krel ff --branch <release-branch> [--ref <master-ref>] [--nomock] [--cleanup] [flags]
31+
```
32+
33+
### Command Line Flags
34+
```
35+
--branch string branch
36+
-h, --help help for ff
37+
--ref string ref on master (default "origin/master")
38+
```
39+
40+
### Example
41+
```bash
42+
krel ff --branch release-1.17 --ref origin/master --cleanup
43+
```

‎docs/krel/gcbmgr.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,7 @@
2626

2727
## Installation
2828

29-
From this root of this repo:
30-
31-
```shell
32-
./compile-release-tools krel
33-
```
29+
Simply [install krel](README.md#installation).
3430

3531
<!-- TODO(vdf): Need to reference K8s Infra projects in usage examples -->
3632
## Usage

‎docs/krel/patch-announce.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# krel patch-anounce
2+
Send out patch release announcement emails
3+
4+
- [Summary](#summary)
5+
- [Installation](#installation)
6+
- [Usage](#usage)
7+
- [Important notes](#important-notes)
8+
9+
10+
## Summary
11+
The `krel patch-announce` subcommand sends out email messages to notify developers about a release. To send the email messages, it needs a Sendgrid API Key and an GitHub token
12+
13+
## Installation
14+
Tu run the `patch-announce` subcommand, [install krel](README.md#installation). You will need a Sendgrid token to be able to send messages and a GitHub token to generate the release notes.
15+
16+
## Usage
17+
```
18+
krel patch-announce [flags]
19+
```
20+
21+
### Command line flags
22+
```
23+
-c, --cut-date string date when the patch release is planned to be cut
24+
-f, --freeze-date string date when no CPs are allowed anymore
25+
-g, --github-token string a GitHub token, used r/o for generating the release notes (default $GITHUB_TOKEN)
26+
-h, --help help for patch-announce
27+
-r, --release-repo string local path of the k/release checkout (default "./release")
28+
-e, --sender-email string email sender's address
29+
-n, --sender-name string email sender's name
30+
-s, --sendgrid-api-key string API key for sendgrid
31+
```
32+
33+
### Notification recipients
34+
35+
Currently, `patch-announce` will notify the following addresses:
36+
| Recipient | E-Mail Address |
37+
| --------- | -------------- |
38+
| Kubernetes developer/contributor discussion | [email protected] |
39+
| kubernetes-dev-announce | [email protected] |
40+
41+

‎docs/krel/push.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# krel push
2+
Push Kubernetes release artifacts to Google Cloud Storage (GCS)
3+
4+
- [Summary](#summary)
5+
- [Installation](#installation)
6+
- [Usage](#usage)
7+
- [Important notes](#important-notes)
8+
9+
## Summary
10+
Used for pushing developer builds and Jenkins' continuous builds.
11+
12+
## Installation
13+
14+
Simply [install krel](README.md#installation).
15+
16+
## Usage
17+
18+
```
19+
krel push [--noupdatelatest] [--ci] [--bucket=<GS bucket>] [--private-bucket] [flags]
20+
```
21+
22+
Developer pushes simply run as they do pushing to devel/ on GCS.
23+
In `--ci` mode, 'push' runs in mock mode by default. Use `--nomock` to do a real push.
24+
25+
### Command line flags
26+
```
27+
--allow-dup Do not exit error if the build already exists on the gcs path
28+
--bucket string Specify an alternate bucket for pushes (normally 'devel' or 'ci') (default "devel")
29+
--buildDir string Specify an alternate build directory (defaults to '_output') (default "_output")
30+
--ci Used when called from Jenkins (for ci runs)
31+
--docker-registry string If set, push docker images to specified registry/project
32+
--extra-publish-file string Used when need to upload additional version file to GCS. The path is relative and is append to a GCS path. (--ci only)
33+
--gcs-suffix string Specify a suffix to append to the upload destination on GCS
34+
-h, --help help for push
35+
--noupdatelatest Do not update the latest file
36+
--private-bucket Do not mark published bits on GCS as publicly readable
37+
--release-type string Specify an alternate bucket for pushes (normally 'devel' or 'ci') (default "devel")
38+
--version-suffix string Append suffix to version name if set
39+
```
40+
### Examples
41+
42+
Do a developer push:
43+
44+
```krel push```
45+
46+
Do a (non-mocked) CI push:
47+
48+
```krel push --nomock --ci```
49+
50+
Do a developer push to kubernetes-release-$USER
51+
52+
```push --bucket=kubernetes-release-$USER```
53+
54+
## Important Notes

‎docs/krel/release-notes.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# krel release-notes
2+
The subcommand of choice for the Release Notes subteam of SIG Release
3+
4+
- [Summary](#summary)
5+
- [Installation](#installation)
6+
- [Usage](#usage)
7+
- [Important notes](#important-notes)
8+
9+
## Summary
10+
11+
The `release-notes` subcommand of krel is used to generate the release notes
12+
draft of a kubernetes version. The subcommand can be used to generate release notes
13+
files for a specific tag or a range of tags. It can output the notes files to Markdown or JSON formats.
14+
15+
This subcommand can be used to generate the release notes draft for the current development version of kubernetes and the JSON version that power relnotes.k8s.io.
16+
`krel release-notes` will create a branch in a user's fork of the corresponding repositories, commit and push the changes. Filing the final PRs to the kubernetes org repositories is in development and will soon be ready.
17+
18+
## Installation
19+
After [installing krel](README.md#installation), you will need to [get a GitHub token](https://github.com/settings/tokens) to run the release-notes subcommand.
20+
21+
If you want to generate the JSON patches for relnotes.k8s.io you will need to have [npm](https://www.npmjs.com/) installed to run the JSON formatter.
22+
23+
## Usage
24+
25+
Before running `krel release-notes` export your GitHub token to $GITHUB_TOKEN:
26+
```
27+
export GITHUB_TOKEN=YOURTOKENHERE
28+
krel release-notes [flags]
29+
```
30+
31+
### Command line flags
32+
```
33+
--create-draft-pr create the Release Notes Draft PR. --draft-org and --draft-repo must be set along with this option
34+
--create-website-pr generate the Releas Notes to a local fork of relnotes.k8s.io and create a PR. --draft-org and --draft-repo must be set along with this option
35+
--draft-org string a Github organization owner of the fork of k/sig-release where the Release Notes Draft PR will be created
36+
--draft-repo string the name of the fork of k/sig-release, the Release Notes Draft PR will be created from this repository (default "sig-release")
37+
--format string The format for notes output (options: markdown, json) (default "markdown")
38+
-h, --help help for release-notes
39+
--kubernetes-sigs-fork-path string fork kubernetes-sigs/release-notes and output a copy of the json release notes to this directory (default "/tmp/k8s-sigs")
40+
-o, --output-dir string output a copy of the release notes to this directory (default ".")
41+
--sigrelease-fork-path string fork k/sig-release and output a copy of the release notes draft to this directory (default "/tmp/k8s-sigrelease")
42+
-t, --tag string version tag for the notes
43+
--website-org string a Github organization owner of the fork of kuberntets-sigs/release-notes where the Website PR will be created
44+
--website-repo string the name of the fork of kuberntets-sigs/release-notes, the Release Notes Draft PR will be created from this repository (default "release-notes")
45+
```
46+
47+
48+
### Examples
49+
50+
`krel release-notes` has three main modes of operation:
51+
52+
#### Ouput the Releas Notes to a single file
53+
The following command will generate the release notes for the 1.18 branch up to beta.2 in /var/www/html/
54+
55+
```bash
56+
krel release-notes -o /var/www/html/ --format markdown --tag v1.18.0-beta.2
57+
```
58+
#### Generate the current markdown draft
59+
This invocation will generate the release notes draft [published in sig-release](https://github.com/kubernetes/sig-release/blob/master/releases/release-1.18/release-notes-draft.md). It will generate the draft for the v1.18 branch up to rc.1. The draft will be written in my local fork of kubernetes/sig-release. `krel release-notes` will clone k/sig-release, create a branch, write the draft and then push the changes back to github, in `kubefriend/sig-release`.
60+
61+
```bash
62+
krel release-notes --create-draft-pr --tag v1.18.0-rc.1 --draft-org=kubefriend
63+
```
64+
65+
#### Update the relnotes.k8s.io website
66+
The subcommand can also generate the notes and modify the necessary files to update the [release notes website](https://relnotes.k8s.io/). This invocation will clone the [release-notes repo](https://github.com/kubernetes-sigs/release-notes) and add my fork as a remote (kubefriend/release-notes). It will then create a feature branch to commit the notes up to v1.18 alpha.1 and update the website files. Finally it will push the changes to my GitHub repo:
67+
68+
```bash
69+
krel release-notes --tag v1.18.0-alpha.1 --website-org=kubefriend --create-website-pr
70+
```
71+
## Important notes
72+
73+
The /tmp defaults shown in the flags above are for Linux. Other platform will default to Go's `os.TempDir()` (for example, on a the Mac the actual path will be under `/var/folders/…` ).
74+
75+
The release-notes subcommand will eventually create the PR for you. This is still under development though.

0 commit comments

Comments
 (0)