Skip to content

Commit 913cbf7

Browse files
authored
Version and release documentation (#531)
* .gitignore,Makefile: added 'build' Makefile target to build a binary within project context (in 'build' dir), and .gitignore clause * doc/release-versioning.md: rough draft of release and versioning semantics and mechanics * Makefile: add mutiple build targets and reformat 'all' make target * release.sh: tag and build release with a few pre-build checks * Makefile: added signature make targets to run under release target * doc/release-versioning.md: revised release process such that 'release.sh' automates everything from building multi-arch to signing * Makefile: add '--tags' flag when retrieving version so the current tag is retrieved regardless of signature * Makefile: ensure git and gpg are configured to have the same signing key * doc/release-versioning.md: document supported k8s versions, architectures, and platforms in their own section * release.sh,Makefile,pkg/generator/templates.go: check versions before tagging on release
1 parent 70b4502 commit 913cbf7

File tree

5 files changed

+222
-9
lines changed

5 files changed

+222
-9
lines changed

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,3 +103,6 @@ tags
103103

104104

105105
# End of https://www.gitignore.io/api/go,vim,emacs,visualstudiocode
106+
107+
# Build artifacts
108+
build/*

Makefile

Lines changed: 51 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,58 @@
1-
pkgs = $(shell go list ./... | grep -v /vendor/)
1+
# kernel-style V=1 build verbosity
2+
ifeq ("$(origin V)", "command line")
3+
BUILD_VERBOSE = $(V)
4+
endif
25

3-
all: format test install
6+
ifeq ($(BUILD_VERBOSE),1)
7+
Q =
8+
else
9+
Q = @
10+
endif
411

5-
install:
6-
go install github.com/operator-framework/operator-sdk/commands/operator-sdk
12+
VERSION = $(shell git describe --dirty --tags)
13+
REPO = github.com/operator-framework/operator-sdk
14+
BUILD_PATH = $(REPO)/commands/operator-sdk
15+
PKGS = $(shell go list ./... | grep -v /vendor/)
16+
17+
export CGO_ENABLED:=0
18+
19+
all: format test build/operator-sdk
720

821
format:
9-
go fmt $(pkgs)
22+
$(Q)go fmt $(PKGS)
1023

1124
dep:
12-
dep ensure -v
25+
$(Q)dep ensure -v
26+
27+
clean:
28+
$(Q)rm -rf build
29+
30+
.PHONY: all test format dep clean
31+
32+
install:
33+
$(Q)go install $(BUILD_PATH)
34+
35+
release_x86_64 := \
36+
build/operator-sdk-$(VERSION)-x86_64-linux-gnu \
37+
build/operator-sdk-$(VERSION)-x86_64-apple-darwin
38+
39+
release: clean $(release_x86_64)
40+
41+
build/operator-sdk-%-x86_64-linux-gnu: GOARGS = GOOS=linux GOARCH=amd64
42+
build/operator-sdk-%-x86_64-apple-darwin: GOARGS = GOOS=darwin GOARCH=amd64
43+
44+
build/%:
45+
$(Q)$(GOARGS) go build -o $@ $(BUILD_PATH)
46+
47+
DEFAULT_KEY = $(shell gpgconf --list-options gpg \
48+
| awk -F: '$$1 == "default-key" { gsub(/"/,""); print $$10}')
49+
build/%.asc:
50+
ifeq ("$(DEFAULT_KEY)","$(shell git config --get user.signingkey)")
51+
$(Q)gpg --output $@ --detach-sig build/$*
52+
$(Q)gpg --verify $@ build/$*
53+
else
54+
@echo "git and/or gpg are not configured to have default signing key ${DEFAULT_KEY}"
55+
@exit 1
56+
endif
1357

14-
.PHONY: all install test format dep
58+
.PHONY: install release_x86_64 release

doc/release-versioning.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Versioning
2+
3+
The following is a concise explanation of how Operator SDK versions are determined. The Operator SDK versioning follows [semantic versioning][link-semver] standards.
4+
5+
## Milestones
6+
7+
Operator SDK [milestones][link-github-milestones] represent changes to the SDK spanning multiple issues, such as a design change. Milestones help SDK developers determine how close we are to new releases, either major or minor; a milestone must be completed before a new version is released. Milestones and their involved issues are determined by maintainers.
8+
9+
Milestone labels have the form: `milestone-x.y.0`, where `x` and `y` are major and minor SDK versions, respectively. This particular milestone demarcates the SDK `x.y.0` release; once issues within this milestone are addressed, the release process can begin.
10+
11+
## Major versions
12+
13+
Major version changes can break compatibility between the previous major versions; they are not necessarily backwards or forwards compatible. SDK change targets include but are not limited to:
14+
- `operator-sdk` command and sub-commands
15+
- Golang API
16+
- Formats of various yaml manifest files
17+
18+
## Minor versions
19+
20+
Minor version changes will not break compatibility between the previous minor versions; to do so is a bug. SDK changes will involve addition of optional features, non-breaking enhancements, and *minor* bug fixes identified from previous versions.
21+
22+
### Creating a minor version branch
23+
24+
We expect to release patches for minor releases, so we create a patch trunk to branch from. The naming convention follows "v2.1.x", where the major version is 2, minor is 1, and "x" is a patch version placeholder.
25+
26+
```bash
27+
$ MAV_MIN_VER="v${MAJOR_VERSION}.${NEW_MINOR_VERSION}"
28+
$ git checkout -b "${MAJ_MIN_VER}.x" tags/"v${MAJ_MIN_VER}.0"
29+
$ git push [email protected]:operator-framework/operator-sdk.git "v${MAJ_MIN_VER}.x"
30+
```
31+
32+
## Patch versions
33+
34+
Patch versions changes are meant only for bug fixes, and will not break compatibility of the current minor version. A patch release will contain a collection of minor bug fixes, or individual major and security bug fixes, depending on severity.
35+
36+
### Creating a patch version branch
37+
38+
As more than one patch may be created per minor release, patch branch names of the form "${MAJOR_VERSION}.${MINOR_VERSION}.${PATCH_VERSION}" will be created after a bug fix has been pushed, and the bug fix branch merged into the patch branch only after testing.
39+
40+
```bash
41+
$ git checkout "v${MAJOR_VERSION}.${MINOR_VERSION}.x"
42+
$ git checkout -b "cherry-picked-change"
43+
$ git cherry-pick "$GIT_COMMIT_HASH"
44+
$ git push origin "cherry-picked-change"
45+
```
46+
47+
# Releases
48+
49+
Making an Operator SDK release involves:
50+
- Tagging and signing a git commit and pushing the tag to GitHub.
51+
- Building a release binary and uploading the binary to GitHub.
52+
53+
Releases can only be performed by [maintainers][doc-maintainers].
54+
55+
## Dependency and platform support
56+
57+
### Kubernetes versions
58+
59+
As the Operator SDK interacts directly with the Kubernetes API, certain API features are assumed to exist in the target cluster. The currently supported Kubernetes version will always be listed in the SDK [prerequisites section][doc-kube-version].
60+
61+
### Operating systems and architectures
62+
63+
Release binaries will be built for the `x86_64` architecture for both GNU Linux and MacOS Darwin platforms.
64+
65+
Support for the Windows platform or any architecture other than `x86_64` is not on the roadmap at this time.
66+
67+
## Binaries
68+
69+
Creating release binaries:
70+
```bash
71+
$ ./release.sh "v${VERSION}"
72+
```
73+
74+
## Release tags
75+
76+
Every release will have a corresponding git tag.
77+
78+
Make sure you've [uploaded your GPG key][link-github-gpg-key-upload] and configured git to [use that signing key][link-git-config-gpg-key] either globally or for the Operator SDK repository. Note: the email the key is issued for must be the email you use for git.
79+
80+
```bash
81+
$ git config [--global] user.signingkey "$GPG_KEY_ID"
82+
$ git config [--global] user.email "$GPG_EMAIL"
83+
```
84+
85+
Tagging will be handled by `release.sh`.
86+
87+
## Release Notes
88+
89+
Release notes should be a thorough description of changes made to code, documentation, and design. Individual changes, such as bug fixes, should be given their own bullet point with a short description of what was changed. Issue links and handle of the developer who worked on the change should be included whenever possible.
90+
91+
The following is the format for major and minor releases:
92+
93+
```Markdown
94+
[Short description of release (ex. reason, theme)]
95+
96+
### Features
97+
- [Short description of feature] (#issue1, #issue2, ..., @maintainer_handle)
98+
...
99+
100+
### Bug fixes
101+
- [Short description of fix] (#issue1, #issue2, ..., @maintainer_handle)
102+
...
103+
104+
### Miscellaneous
105+
- [Short description of change] (#issue1, #issue2, ..., @maintainer_handle)
106+
...
107+
```
108+
109+
Patch releases should have the following format:
110+
111+
```Markdown
112+
[Medium-length description of release (if not complex, short is fine); explanation required]
113+
114+
### Bug fixes
115+
- [Short description of fix] (#issue1, #issue2, ..., @maintainer_handle)
116+
...
117+
```
118+
119+
[link-semver]:https://semver.org/
120+
[link-github-milestones]: https://help.github.com/articles/about-milestones/
121+
[doc-maintainers]:../MAINTAINERS
122+
[link-github-gpg-key-upload]:https://github.com/settings/keys
123+
[link-git-config-gpg-key]:https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work
124+
[doc-kube-version]:https://github.com/operator-framework/operator-sdk#prerequisites

pkg/generator/templates.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -324,8 +324,8 @@ required = [
324324
[[constraint]]
325325
name = "github.com/operator-framework/operator-sdk"
326326
# The version rule is used for a specific release and the master branch for in between releases.
327-
branch = "master"
328-
# version = "=v0.0.6"
327+
branch = "master" #osdk_branch_annotation
328+
# version = "=v0.0.6" #osdk_version_annotation
329329
`
330330

331331
const projectGitignoreTmpl = `

release.sh

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
#!/usr/bin/env bash
2+
3+
set -e
4+
5+
[ $# == 1 ] || { echo "usage: $0 version" && exit 1; }
6+
7+
VER=$1
8+
9+
[[ "$VER" =~ ^v[[:digit:]]+\.[[:digit:]]+\.[[:digit:]]+$ ]] || {
10+
echo "malformed version: \"$VER\""
11+
exit 2
12+
}
13+
14+
if test -n "$(git ls-files --others | \
15+
grep --invert-match '\(vendor\|build/operator-sdk-v.\+\)')";
16+
then
17+
echo "directory has untracked files"
18+
exit 1
19+
fi
20+
21+
if ! $(git diff-index --quiet HEAD --); then
22+
echo "directory has uncommitted files"
23+
exit 1
24+
fi
25+
26+
# Detect whether versions in code were updated.
27+
CURR_VER="$(git describe --dirty --tags)"
28+
VER_FILE="version/version.go"
29+
TOML_TMPL_FILE="pkg/generator/templates.go"
30+
CURR_VER_VER_FILE="$(sed -nr 's/Version = "(.+)"/\1/p' "$VER_FILE" | tr -d '\s\t\n')"
31+
CURR_VER_TMPL_FILE="$(sed -nr 's/.*".*v(.+)".*#osdk_version_annotation/v\1/p' "$TOML_TMPL_FILE" | tr -d '\s\t\n')"
32+
if [ "$CURR_VER" != "$CURR_VER_VER_FILE" ] \
33+
|| [ "$CURR_VER" != "$CURR_VER_TMPL_FILE" ]; then
34+
echo "versions are not set correctly in $VER_FILE or $TOML_TMPL_FILE"
35+
exit 1
36+
fi
37+
38+
git tag --sign --message "Operator SDK $VER" "$VER"
39+
40+
git verify-tag --verbose "$VER"
41+
42+
make release

0 commit comments

Comments
 (0)