Skip to content

Define coordinated releases and date-based naming scheme. #26

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

Closed
evankanderson wants to merge 2 commits into from
Closed

Define coordinated releases and date-based naming scheme. #26

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c4fae02
Define coordinated releases and date-based naming scheme.
evankanderson Aug 8, 2019
535c04f
Update date-based versioning guidelines to spell out where each versi…
evankanderson Aug 9, 2019
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
65 changes: 65 additions & 0 deletions mechanics/Release-Mechanics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Release Mechanics
Copy link
Copy Markdown
Contributor

@RichieEscarez RichieEscarez Nov 15, 2019

Choose a reason for hiding this comment

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

Adding missing frontmatter for rendering on Knative.dev
Note: weight: 60 indicates its position in the nav tree relative to the weights of the other files in the /mechanics/ directory (given existing files, 60 places this at the bottom).

By default we have been adding by 10's, but if you want this higher and next to another existing file, you can increment by 1's to insert (ie: if README.md is 10, and you want this directly below, set this to 11 or 15 to allow room for future files above and below)

Suggested change
# Release Mechanics
---
title: "Knative release mechanics"
linkTitle: "Release mechanics"
weight: 60
type: "docs"
---


Knative core components (repo) releases from master are coordinated for the
following reasons:

1. Coordinated release makes it easier to release documentation and other
cross-cutting repositories.
1. Coordinated release makes it easier for operators to install and describe
what release they are running.
1. Coordinated release makes it easier to test compatibility across repos,
though cross-repo dependencies should generally be supported at least +/- 1
revision (i.e. revision N+1 of repo X should work with revision N of repo Y
and vice-versa).

**Patch (cherrypick) releases are not coordinated across repos**; it is expected
that each repo will perform patch releases for critical bugs and security issues
for the last 2 releases.

## Release Schedule

Knative releases will be cut (automatically) every 6 weeks. Any change to this
Copy link
Copy Markdown
Contributor

@pmorie pmorie Aug 15, 2019

Choose a reason for hiding this comment

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

How automatic is "automatic" here? Does that mean we will have machinery/automation that literally automatically does the release, and we consider green CI meaning "ready to release", or something else?

schedule should be coordinated by the TOC.

<!-- TODO: do we have a calendar for this? What about releases during holidays like Christmas? -->

## Release Naming

Regular releases from master will be named by the date of the release in ISO
date format (e.g. `2019-08-06`). Patch releases will be named as `2019-08-06.1`,
`2019-08-06.2`, etc. The head release will be named without a ".0" suffix; the
Copy link
Copy Markdown
Member

@mattmoor mattmoor Aug 9, 2019

Choose a reason for hiding this comment

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

I recall that you are avoiding the Docker scheme of YYYY.MM.PATCH for a reason. Perhaps worth commenting given the similarity of that scheme?

Copy link
Copy Markdown
Member Author

@evankanderson evankanderson Aug 9, 2019

Choose a reason for hiding this comment

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

Since we have an every 6-week schedule, YYYY.MM.PATCH would work (though we'll occaisonally skip a month, like October). I'm fine with that format.

Copy link
Copy Markdown
Contributor

@pmorie pmorie Aug 15, 2019

Choose a reason for hiding this comment

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

If we were to return the format currently in the PR (yyyy-mm-dd) I would ask to consider three character months instead of names, since interpretation of the suggested format is subjective and different countries/cultures have different schemes (yyyy-dd-mm vs yyyy-mm-dd)

first patch (cherrypick) release should be named ".1", with each subsequent
patch incrementing the number.

Each repo should define a mapping from the canonical date-based format to a
Copy link
Copy Markdown

@akashrv akashrv Aug 8, 2019

Choose a reason for hiding this comment

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

Overall looks good. It will be helpful if we standardize how this is defined (or exposed to end-users) such that an end-user has a consistent way of figuring out mapping from date --> semver for all knative repos.

Copy link
Copy Markdown
Member Author

@evankanderson evankanderson Aug 8, 2019

Choose a reason for hiding this comment

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

Do you have a proposal for where this should go?

I wanted to get a base-line recommendation in here and then iterate on the mapping documentation based on feedback from docs/WG leads.

Copy link
Copy Markdown

@akashrv akashrv Aug 9, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

thinking more about it there I think we need to clarify more in this doc - What does release naming mean and how end-users discover it? (it could also be my lack of knowledge, so please point me to docs if that is the case :))
Today when we release there are multiple places that we mention the semver:

  • release branch name
  • tag in github
  • labels on k8s artifacts
  • tag in the container images (our docs recommend customers to see this to figure out the version they have installed)
  • docs page dropdown.

semver carries a sematic meaning so I believe we want to continue with it.
However with each component updating semver differently (example eventing v0.10, serving v1.0), we want to tie them together with a date based version.

So the question is what that date based version exactly mean and where do users see it? Clarifying that in this doc is important.
One option could be - let each repo continue what they are doing right now.
In docs have a page that maintains the mapping of date-semver, and each repo's release notes maintains it for its own release.
We could also have both date and semver in the version labels and tags. We can figure this out and come up with proposals.

However, clarifying exactly where the date based version or Release Name will appear and how users will see it is needed in this doc. Then we can come up with a scheme for the mapping to semver. Makes sense?

Copy link
Copy Markdown
Member Author

@evankanderson evankanderson Aug 9, 2019

Choose a reason for hiding this comment

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

I would use the date-based names in all of the above automated locations.

I might include the semantic version on the landing page for the component, ala https://knative.dev/docs/serving might say:

Knative Serving (v1.1)

Copy link
Copy Markdown

@akashrv akashrv Aug 12, 2019

Choose a reason for hiding this comment

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

That sounds good to me. Along with the landing page semantic versioning could also be mentioned with release notes in Github (along with the date-based version).
About date-based v/s just a number, I would prefer date-based as it conveys an extra bit of information about the release date along with the sequential info.

Copy link
Copy Markdown
Contributor

@pmorie pmorie Aug 15, 2019

Choose a reason for hiding this comment

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

What semVer would a patch release have?

traditional [Semantic Versioning](https://semver.org) minor version number. Note
that these mappings may not be the same between repos; for example,
`knative/serving` might map `2019-11-05` to "1.1", but `knative/observability`
might map the same release to "0.10".
Copy link
Copy Markdown
Member

@mattmoor mattmoor Aug 9, 2019

Choose a reason for hiding this comment

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

We use these versions in a few contexts (e.g. release branch names). Where would we use each of the split version numbers?

Copy link
Copy Markdown
Member Author

@evankanderson evankanderson Aug 9, 2019

Choose a reason for hiding this comment

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

See my reply to @akashrv #26 (comment)

I would use the date-based release string for the branch name and artifact names, as well as for the k8s labels and the version selector in the docs repo.


Date-based version numbers will be used for all of the following:

- release branch name
- docs page dropdown
Copy link
Copy Markdown
Contributor

@pmorie pmorie Aug 15, 2019

Choose a reason for hiding this comment

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

I'd really expect to use a semver coordinate in such a dropdown.

- tag in the container images (the date-based tag will point to the most recent
patch release of that date-based branch)

Date + patch version numbers will be used for the following:

- tag in github (as there may be multiple tagged releases on the same branch in
the case of patches)
- label on k8s artifacts (so that users can determine whether their resources
are up to date with the latest patch release)
- tag in the container images (the exact date+patch tag should be kept both for
reference by released yaml and to be able to work backwards from a docker
image to the release information)

Semantic versions should (at least) be referenced in the main documentation
page, e.g. https://knative.dev/docs/serving

## Historical Background

Historically (up to 0.8), Knative releases were named using 0.X (major version =
0, minor version incrementing on each release.) Since around January 2019, the
Knative release schedule has been every 6 weeks; around March 2019, this was
automated.