Version and release documentation #531

estroz · 2018-09-25T21:15:20Z

This PR contains documentation outlining how releases will be done, release semantics, and versioning. The release and versioning documentation is a now in final draft form.

Resolves: #166, #476

Note: discussion of PGP key signing process has been moved to #588

robszumski · 2018-09-25T21:25:26Z

This is off to a great start. Brainstorming other topics we might want to cover that are less about the mechanics and more about how it affects an Operator developer:

releases will generally support a range of Kubernetes versions. Should we document this? Is there any expectation that we can set?
info about taking an existing codebase and adding a new version of the SDK to it. What do you do, in broad strokes?

AlexNPavel · 2018-09-25T21:58:26Z

@estroz Can you rebase these commits? Due to the way travis works, there's some dependency issues that should be fixed by simply rebasing.

AlexNPavel

Overall, the release process seems pretty reasonable, but we need to make sure we build for all supported platforms, and we should probably automate some of these steps to reduce the chance of mistakes.

AlexNPavel · 2018-09-25T22:19:55Z

doc/release-versioning.md

+
+## Binaries
+
+Release binaries will be built for the `x86_64` architecture. Binaries will be signed using a maintainers' [PGP key][doc-maintainer-pgp-keys], and signatures will be uploaded to the release along with its accompanying tarball-ed binary. Ensure you import maintainer keys to verify release binaries. Note: `gpg` and `gpg2` can be used interchangeably to sign and verify binaries; substitute `gpg2` for `gpg` below.


Why are we tarballing the binary (and the build directory as a whole)? Most projects I've seen just upload the raw binary as their release (and most exceptions include more than 1 file, such as openshift/origin which also includes a license and readme). Uploading just a raw binary makes it easier to download and use the binary as well.

Makes sense to me.

AlexNPavel · 2018-09-25T22:22:46Z

doc/release-versioning.md

+
+Creating a release binary tarball:
+```bash
+$ make build


make build just builds the binary for architecture and os of the current machine. We should have a make release function that cross-compiles for all supported platforms (linux and macos x86_64). I built a release for ct last year, which has a pretty well designed release process. This is their makefile (they support many more platforms than us, but still a good reference): https://github.com/coreos/container-linux-config-transpiler/blob/master/Makefile

Ah excellent. I wasn't sure which architectures were supported so I assumed only linux x86_64 was. I will make updates to the Makefile.

AlexNPavel · 2018-09-25T22:27:41Z

doc/release-versioning.md

+```bash
+$ git tag \
+    -s "v${MAJOR_VERSION}.${MINOR_VERSION}.${PATCH_VERSION}" \
+    "$GIT_COMMIT_HASH"


There's a lot of different steps to perform to do a release and that leaves a lot of room for error. A script might make sense to help simplify this. As I mentioned in an above comment, ct has a pretty nice release process. They have a script that does various checks, creates and verifies a signed tag, and then runs make release. I feel that this would work well for our release process as well: https://github.com/coreos/container-linux-config-transpiler/blob/master/release.sh

I fully agree. I'll take a look at that script and make adaptions.

AlexNPavel · 2018-09-25T22:57:28Z

Something I forgot to mention in my first lookthrough of this: we need to update the version we are pointing to in pkg/generator/templates.go and update the version in version.go. See PR #457.

lilic

In general lgtm, but agree with @AlexNPavel it should be more automated.

lilic · 2018-09-26T10:39:44Z

doc/release-versioning.md

+$ make build
+```
+
+Creating a release tarball:


Can we automate the following parts as well, we could have a script that does all these steps for us. You could pass in the needed args but it should be possible to automate.

Done as per @AlexNPavel 's comments.

lilic · 2018-09-26T10:51:52Z

releases will generally support a range of Kubernetes versions. Should we document this? Is there any expectation that we can set?

We should just document the minimum supported version of Kubernetes, which is already documented in https://github.com/operator-framework/operator-sdk#prerequisites, don't think it needs to be in the release notes as well.

shawn-hurley · 2018-09-26T13:41:27Z

doc/release-versioning.md

+
+Making an Operator SDK release involves:
+- Tagging and signing a git commit and pushing the tag to GitHub.
+- Building a release binary, signing the binary, and uploading both binary and signature to GitHub.


As part of this, I would like to see discussion about releasing ansible operator base image and helm operator along with the binary.

I think that we should start thinking about all of these things as 1 project and not separate entities with their own release timelines or procedures.

In this case, I believe that a tagged version of the ansible-operator base image (and maybe the binary as well?) should be built, and pushed to a shared quay.io repo. I would like this to happen at the exact same time that operator-sdk release is happening.

I believe the helm-operator should have a published binary and base-image. I don't know enough about how it is expected to be used to comment much further.

@spahl @AlexNPavel @robszumski can you comment on this? Not sure if ansible image packaging has been discussed outside of this PR. This suggestion sounds reasonable to me but needs its own PR.

We should do this in a separate PR. I do agree that it should be tracked and released at the same time. Let's create an issue to not forget.

estroz · 2018-09-26T20:14:49Z

@AlexNPavel I've adopted the release.sh and Makefile targets you linked. Let me know if they look reasonable. Updates were made to the release sections to focus on using release.sh instead of manual command entry.

AlexNPavel · 2018-09-27T20:22:13Z

When running make install, we now generate a operator sdk that says it was not built properly when you try to get the version, which isn't exactly true; we just built a dirty version. I feel that we should set the version to the git dirty number. Currently, the git describe --dirty shell is failing for me, but adding --tags fixes that. If we then enable LD_FLAGS for make install, we get versions like v0.0.5-307-g1752a92-dirty, which is a more reasonable and descriptive version number for dirty builds.

estroz · 2018-10-01T18:35:33Z

@lilic @robszumski noted the location of Kubernetes version info.

Do we want to have a compatibility matrix for the SDK, as suggested in this issue comment?

estroz · 2018-10-02T23:23:31Z

doc/release-versioning.md

+
+## Binaries and signatures
+
+Binaries will be signed using a maintainers' [PGP key][doc-maintainer-pgp-keys], and signatures will be uploaded to the release along with its accompanying binary. Ensure you import maintainer keys to verify release binaries.


Before this PR is merged we need to have a discussion about signing processes and handling maintainer PGP keys.

shawn-hurley

LGTM pending the discussion about signing and handling maintainer PGP keys.

…within project context (in 'build' dir), and .gitignore clause

…ntics and mechanics

These Makefile updates allow the SDK to be built for multiple platforms with one command, 'make release'

…move arm64 release make target

….sh' automates everything from building multi-arch to signing

…g is retrieved regardless of signature

…d Kubernetes version(s)

…ures, and platforms in their own section

… tagging on release

AlexNPavel

LGTM

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

* .gitignore,Makefile: added 'build' Makefile target to build a binary within project context (in 'build' dir), and .gitignore clause * Makefile: add mutiple build targets and reformat 'all' make target * Makefile: added signature make targets to run under release target * 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

… (operator-framework#604) * .gitignore,Makefile: added 'build' Makefile target to build a binary within project context (in 'build' dir), and .gitignore clause * Makefile: add mutiple build targets and reformat 'all' make target * Makefile: added signature make targets to run under release target * 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

* .gitignore,Makefile: added 'build' Makefile target to build a binary within project context (in 'build' dir), and .gitignore clause * Makefile: add mutiple build targets and reformat 'all' make target * Makefile: added signature make targets to run under release target * 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

estroz added needs discussion docs do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Sep 25, 2018

estroz requested review from AlexNPavel, hasbro17, lilic, rithujohn191, robszumski and spahl September 25, 2018 21:15

openshift-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Sep 25, 2018

estroz force-pushed the version-release-doc branch from 3cdb811 to 43e5b24 Compare September 25, 2018 22:29

AlexNPavel suggested changes Sep 25, 2018

View reviewed changes

lilic suggested changes Sep 26, 2018

View reviewed changes

shawn-hurley requested changes Sep 26, 2018

View reviewed changes

estroz force-pushed the version-release-doc branch from 1752a92 to f496a95 Compare September 28, 2018 18:46

estroz mentioned this pull request Oct 1, 2018

Release ansible base image/binary #555

Closed

estroz changed the title ~~[WIP] Version and release documentation~~ Version and release documentation Oct 1, 2018

openshift-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 1, 2018

AlexNPavel approved these changes Oct 2, 2018

View reviewed changes

estroz commented Oct 2, 2018

View reviewed changes

estroz added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 2, 2018

shawn-hurley approved these changes Oct 3, 2018

View reviewed changes

estroz added 14 commits October 9, 2018 18:06

.gitignore,Makefile: added 'build' Makefile target to build a binary …

d83283d

…within project context (in 'build' dir), and .gitignore clause

doc/release-versioning.md: rough draft of release and versioning sema…

00bc43d

…ntics and mechanics

Makefile: add mutiple build targets and reformat 'all' make target

43a8fa0

These Makefile updates allow the SDK to be built for multiple platforms with one command, 'make release'

release.sh: tag and build release with a few pre-build checks

6b174c3

Makefile: add BUILD_PATH variable to identify the correct main.go, re…

0fb2072

…move arm64 release make target

Makefile: added signature make targets to run under release target

d023aef

doc/release-versioning.md: revised release process such that 'release…

2ae7704

….sh' automates everything from building multi-arch to signing

doc/release-versioning.md: simplified code example

91e62e1

Makefile: removed commented code

8c89645

Makefile: add ldflags to 'install' make target

ef73041

Makefile: add '--tags' flag when retrieving version so the current ta…

da7016c

…g is retrieved regardless of signature

doc/release-versioning.md: add section detailing location of supporte…

7229a35

…d Kubernetes version(s)

Makefile: ensure git and gpg are configured to have the same signing key

8eeb815

doc/release-versioning.md: document supported k8s versions, architect…

94a88e1

…ures, and platforms in their own section

estroz force-pushed the version-release-doc branch from 82b7bda to 54267d2 Compare October 10, 2018 01:06

estroz added 2 commits October 10, 2018 14:54

release.sh,Makefile,pkg/generator/templates.go: check versions before…

9a487e9

… tagging on release

*: remove PGP signing steps from release process (moving to separate PR)

8fd7047

estroz force-pushed the version-release-doc branch from 54267d2 to 8fd7047 Compare October 10, 2018 21:55

AlexNPavel approved these changes Oct 11, 2018

View reviewed changes

lilic approved these changes Oct 11, 2018

View reviewed changes

estroz merged commit 913cbf7 into operator-framework:master Oct 11, 2018

estroz deleted the version-release-doc branch October 11, 2018 17:58

estroz mentioned this pull request Oct 11, 2018

Windows support #465

Closed

estroz mentioned this pull request Dec 17, 2018

Build, tag, and push operator base images during CI #832

Merged


		## Binaries

		Release binaries will be built for the `x86_64` architecture. Binaries will be signed using a maintainers' [PGP key][doc-maintainer-pgp-keys], and signatures will be uploaded to the release along with its accompanying tarball-ed binary. Ensure you import maintainer keys to verify release binaries. Note: `gpg` and `gpg2` can be used interchangeably to sign and verify binaries; substitute `gpg2` for `gpg` below.


		## Binaries and signatures

		Binaries will be signed using a maintainers' [PGP key][doc-maintainer-pgp-keys], and signatures will be uploaded to the release along with its accompanying binary. Ensure you import maintainer keys to verify release binaries.

Version and release documentation #531

Version and release documentation #531

Uh oh!

Conversation

estroz commented Sep 25, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robszumski commented Sep 25, 2018

Uh oh!

AlexNPavel commented Sep 25, 2018

Uh oh!

AlexNPavel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexNPavel commented Sep 25, 2018

Uh oh!

lilic left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lilic commented Sep 26, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spahl Oct 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

estroz commented Sep 26, 2018

Uh oh!

AlexNPavel commented Sep 27, 2018

Uh oh!

estroz commented Oct 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shawn-hurley left a comment

Choose a reason for hiding this comment

Uh oh!

AlexNPavel left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

estroz commented Sep 25, 2018 •

edited

Loading

spahl Oct 1, 2018 •

edited

Loading

estroz commented Oct 1, 2018 •

edited

Loading