Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refactor documentation #2079

Closed
wants to merge 1 commit into from
Closed

Refactor documentation #2079

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,14 @@
4. If the PR is unfinished, see how to mark it: https://git.k8s.io/community/contributors/guide/pull-requests.md#marking-unfinished-pull-requests
-->

**What this PR does / why we need it**:
**What this PR does / why we need it**: <!-- A concise description of what this PR entails -->

**How does this change affect the cardinality of KSM**: *(increases, decreases or does not change cardinality)*
**How does this change affect the cardinality of KSM**: <!-- Does this PR increase, decrease or does not affect KSM's overall cardinality? -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**How does this change affect the cardinality of KSM**: <!-- Does this PR increase, decrease or does not affect KSM's overall cardinality? -->
**How does this change affect the cardinality of KSM**: <!-- Does this PR increase or decrease the number of metrics or the number labels within specific metrics created? -->

Good idea, I would suggest to explain what cardinality means for folks who are not super familiar.


**Which issue(s) this PR fixes** *(optional, in `fixes #<issue number>(, fixes #<issue_number>, ...)` format, will close the issue(s) when PR gets merged)*:
Fixes #
**Which issue(s) this PR fixes**: <!-- Optional, should be in `Fixes #<issue number>(, fixes #<issue_number>, ...)` format, will close the mentioned issue(s) when PR gets merged -->

**Choose one below, based on the nature of this PR:**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to provide an explanation so it's easier to pick for the contributor?

- [ ] BUGFIX
- [ ] CHANGE
- [ ] ENHANCEMENT
- [ ] FEATURE
77 changes: 50 additions & 27 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,64 @@

## Branch management and versioning strategy

We use [Semantic Versioning](http://semver.org/).
### Semantic versioning

We maintain a separate branch for each minor release, named `release-<major>.<minor>`, e.g. `release-1.1`, `release-2.0`.
We use [Semantic Versioning](http://semver.org/), and thus, maintain a separate branch for each minor release, named
`release-<major>.<minor>`, e.g. `release-1.1`, `release-2.0`.

The usual flow is to merge new features and changes into the main branch and to merge bug fixes into the latest release branch. Bug fixes are then merged into main from the latest release branch. The main branch should always contain all commits from the latest release branch.
### Workflow

If a bug fix got accidentally merged into main, cherry-pick commits have to be created in the latest release branch, which then have to be merged back into main. Try to avoid that situation.
- The usual flow is to merge new features and changes into the main branch and to merge (the later) bug fixes into the
latest release branch.
- Bug fixes are then merged into main from the latest release branch.
- The main branch should always contain **all** commits from the latest release branch.
- If a bug fix got accidentally merged into main, cherry-pick commits have to be created in the latest release branch,
which then have to be merged back into main. Try to avoid that situation.
- Maintaining the release branches for older minor releases happens on a **best effort** basis.

Maintaining the release branches for older minor releases happens on a best effort basis.
## Preparing the release

## Prepare your release
Note: For a stable release, first a release candidate (e.g. `v1.2.0-rc.0`) should be cut. If, after a period of
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note: For a stable release, first a release candidate (e.g. `v1.2.0-rc.0`) should be cut. If, after a period of
Note: For a breaking major release, first a release candidate (e.g. `v3.0.0-rc.0`) should be cut. For minor or patch releases, this is not necessary. If, after a period of

**7 days**, no bugs or issues were reported after publishing the release candidate, a stable release (e.g. `v1.2.0`)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**7 days**, no bugs or issues were reported after publishing the release candidate, a stable release (e.g. `v1.2.0`)
**7 days**, no bugs or issues were reported after publishing the release candidate, a stable release (e.g. `v3.0.0`)

can be cut.

* Bump the version in the `VERSION` file in the root of the repository.
* Run `make examples`, which will re-generate all example manifests to use the new version.
* Make a PR to update:
* [Compatibility matrix](README.md#compatibility-matrix)
* Changelog entry
* Only include user relevant changes
### Workflow

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a couple of steps before, as I believe this order makes more sense:

* If this is a new major or minor release, create a release branch from `main` e.g. `release-2.10`
* Push the release branch to `kubernetes/kube-state-metrics`
* Create a branch `prep-release-v2.10`.

* Bump the version in [`VERSION.md`](VERSION.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Bump the version in [`VERSION.md`](VERSION.md).
* Bump the version in [VERSION](VERSION).

This is not a markdown file but a plain text file.

* Run `make examples`, which will re-generate all example manifests to use the newer version.
* Cut the new release branch, e.g. `release-1.2`, or merge/cherry-pick changes onto the minor release branch you intend
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Cut the new release branch, e.g. `release-1.2`, or merge/cherry-pick changes onto the minor release branch you intend

Handled before

to tag the release on.
* Include the following changes in the release PR (cut from `main`).
* Update the [compatibility matrix](README.md#compatibility-matrix).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Update the [compatibility matrix](README.md#compatibility-matrix).
* Update the [compatibility matrix](README.md#compatibility-matrix) and the link to the container image in [README.md](README.md)

* Add changelog entries.
* Entries in the [`CHANGELOG.md`](CHANGELOG.md) are meant to be in this order:
```
[BUGFIX]
[CHANGE]
[FEATURE]
[ENHANCEMENT]
[BUGFIX]
[FEATURE]
```
* All lines should be full sentences
* kube-state-metrics image tag used in Kubernetes deployment yaml config.
* Cut the new release branch, e.g. `release-1.2`, or merge/cherry-pick changes onto the minor release branch you intend to tag the release on
* Cut the new release tag, e.g. `v1.2.0-rc.0`
* Create a new **pre-release** on github
* New images are automatically built and pushed to `gcr.io/k8s-staging-kube-state-metrics/kube-state-metrics`
* Promote image by sending a PR to [kubernetes/k8s.io](https://github.com/kubernetes/k8s.io) repository. Follow the [example PR](https://github.com/kubernetes/k8s.io/pull/3798). Use [kpromo pr](https://github.com/kubernetes-sigs/promo-tools/blob/main/docs/promotion-pull-requests.md) to update the manifest files in this repository, e.g. `kpromo pr --fork=$YOURNAME -i --project=kube-state-metrics -t=v2.5.0`
* Create a PR to merge the changes of this release back into the main branch.
* Once the PR to promote the image is merged, mark the pre-release as a regular release.

## Stable release

First a release candidate (e.g. `v1.2.0-rc.0`) should be cut. If after a period of 7 days no bugs or issues were reported after publishing the release candidate, a stable release (e.g. `v1.2.0`) can be cut.
* To generate changelog, follow the process below:
* Fetch all commits since last release, for instance, when preparing for `v2.9.0`, do
`git log --oneline --decorate upstream/release-2.8..upstream/main`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't it easier to look at the closed PRs since the previous release?

* Remove all merge commits, `fixup!`s (if any), and any commits that might have crept in from a PR, other
than it's original commit, unless wanted otherwise.
* Remove all non-user-facing changes.
* Label the remaining commits under the aforementioned categories, and futher condense commit groups
under their associated PRs, wherever possible.
* Format the message in the manner: `[<category>] <PR header> <PR number> <Author>`.
* All lines should be full sentences.
* Cut the new release-candidate tag, e.g. `v1.2.0-rc.0`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's cut the release directly and release candidates only for breaking releases.

* Create a new **pre-release**.
* Create a PR to merge the changes of this release back into the `main` branch.
* Once the PR to promote the image is merged, mark the pre-release as a regular release. This must be done after the
**7-day** period is over.

### Post-release chores

* Promote the latest release image, refer [k8s.io/#4750](https://github.com/kubernetes/k8s.io/pull/3798) for more
details. Also see [promotion-pull-requests.md#promoting-images](https://github.com/kubernetes-sigs/promo-tools/blob/main/docs/promotion-pull-requests.md#promoting-images).
* For instance, `kpromo pr --fork mrueg -i --project kube-state-metrics --reviewers="@fpetkovski,@dgrisonnet,@rexagod" -t=v2.8.2 --image="" --digests=""`.
* Open a PR promoting the image (based on aforementioned links).
* New images will be automatically built and pushed to `gcr.io/k8s-staging-kube-state-metrics/kube-state-metrics`.