Define coordinated releases and date-based naming scheme.

[evankanderson]

I promised this last week at the TOC meeting.

Defines a date-based versioning scheme for coordinated future releases.

[knative-prow-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: evankanderson
To complete the pull request process, please assign isdal
You can assign the PR to them by writing /assign @isdal in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[evankanderson]

/assign @mattmoor @vaikas-google @akashrv @markusthoemmes @bbrowning @duglin @jchesterpivotal

I think all the above expressed some interest in how we express versions. Here's the proposal.

[evankanderson]

/hold

Until at least TOC and possibly other interested parties weigh in.

[akashrv]

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.

[evankanderson]

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.

[akashrv]

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?

[evankanderson]

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)

[akashrv]

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.

[pmorie]

What semVer would a patch release have?

[mattmoor]

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

[evankanderson]

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.

[mattmoor]

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?

[evankanderson]

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.

[pmorie]

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)

[rgregg]

I have a suggestion based on some thinking from others. Instead of switching formats to be date-based, what if we continue to use the minor-version == release number, and use the major-number as a production-bit. 1.X releases are "production ready" and "0.X" releases are pre-production. I think this part is already the plan, but the delta would be that we don't reset the minor version when setting the production bit.

In short, we'd have 0.7, 0.8, 1.9, 1.10, 1.11 for serving, and 0.7, 0.8, 0.9, 0.10, for eventing (for now).

This way, we'd still have a clear alignment between releases in different repos, and be able to clearly communicate the production readiness of a given release in a meaningful way.

I think the only "bad taste" part of this is the initial transition from 0.X to 1.X, but that's a point in time problem that goes away after the next release.

I think this would be the smallest change to ensure the outcome we want, without needing to change the way we do things.

[evankanderson]

I've updated the PR with guidance about where to use the date and date.patch release names across the areas suggested by Akash:

• release branch
• release tag
• docker image tag
• label on K8s objects
• docs page

I don't have a strong feeling about whether we use a sequential-number format or a date-based format, so long as it's easy for users to understand and find documentation about the component of interest, and for users to determine how old the version of code they are running is.

[mattmoor]

I'm partial to what @rgregg lists above, it's simple and effective and less of an eyesore.

It will be weird for serving to jump directly to 1.9 (and for things like eventing to go directly to 1.1x), but I still prefer it to the purely date-based scheme. 🤷‍♂

[n3wscott]

How about using semver plus a knative release count number.

So serving and eventing do this:

Serving	Eventing
v0.8.0+kn8	v0.8.0+kn8
v0.9.0+kn9	v0.9.0+kn9
v0.9.1+kn9	-
v1.0.0+kn10	v0.10.0+kn10
-	v0.10.1+kn10

Then Client or whatever new thing that comes out (operator) is v0.1.0+kn13

Update: edited to use version+tag per @scothis 's comment #26 (comment)

Spec: https://semver.org/

We could even invent some kind of build tag that means something to us, like kn<release#>.<build date>

[dprotaso]

For clarity what problem is this proposal trying to solve?

[scothis]

How about using semver plus a knative release count number.
...
Then Client or whatever new thing that comes out (operator) is v0.1.0-kn13

v0.1.0-kn13 in semver is indicative of a pre-release. To annotate a release with build metadata you want v0.1.0+kn13

[n3wscott]

@dprotaso how do you know serving, eventing and the client work well together without a BigDumbTable™️

[dprotaso]

@dprotaso how do you know serving, eventing and the client work well together without a BigDumbTable™️

Cool any other problems we're trying to address?

[n3wscott]

@dprotaso how do you know serving, eventing and the client work well together without a BigDumbTable™️

Cool any other problems we're trying to address?

We would like to signal to folks that Serving will become a full v1.0 type application and preserve the linkage between the projects. Is that what you are asking?

[jchesterpivotal]

I'm generally in favour of lockstep versioning, regardless of the scheme. But I think confusion may arise about the GA levels of different products once they're lashed together. Those who know the landscape well can distinguish the nuances of the different subprojects. Those who are less versed may inadvertently assume that everything is GA, which could lead to a cottage industry of sick burns on Twitter.

One approach would be to hold back on consistent versions until all components are marked as GA. Another would be to hold on 1.0 or calendrical equivalents until all components are judged to be GA-worthy. Another would be annotating the versions somehow, but I think that's the least effective solution.

[dprotaso]

We would like to signal to folks that Serving will become a full v1.0 type application and preserve the linkage between the projects. Is that what you are asking?

Yeah I just want to make these problems visible since there's no mention of why in the actual content of the PR. So if I stumble here without having attended the various meetings I wouldn't understand the what's motivating the change.

[evankanderson]

I think one requirement that somehow got lost here (in my opinion, the biggest issue) is how to represent our coordinated releases in a way which is consumable by users in the following forums (from highest to lowest priority):

1. On https://knative.dev/ documentation drop-down.
2. On releases pages.
3. In release artifacts (yaml / k8s labels and image tags).
4. In branch names.

It's not clear to me how the table proposal handles 1 and 2 in a consumable way.

I'm somewhat concerned about item 1 in the X.10 format @mattmoor proposed.

[mattmoor]

x.10 is literally what I was thinking for 1. 🤓

[duglin]

I've been thinking something similar to what I think @jchesterpivotal said above. It seems to me that once we hit GA (v1.0) that the versioning scheme isn't really that important any more since the version string in the API/YAML will tell us if we're v1 or v2. At that point all that really matters is that all of the components share the same version string (whether it's date base or semVer based).

So, that then leads me to think that this is only a temporary problem and really only because we're claiming that eventing (or other repos) are behind serving. I'd like to push back on this assertion.

What if we reduced eventing's v1.0 scope to just the stuff that's ready - so perhaps some event sources and brokers? All other features can remain as alpha or beta. Going forward we'll need a way to ship non-GA features while also having eventing & serving be at a post-GA level, so why not just use that mechanism now?

Net proposal:

• only have one versioning scheme, not 2 - that's just going to confuse people (I vote for semVer)
• make v1.0 apply to all Knative repos - and that includes the "GA" seal-of-approval
• scope each repo's GA features appropriately and keep all others at some alpha or beta API level

[mattmoor]

What if we reduced eventing's v1.0 scope to just the stuff that's ready

If "ready" means "ready for production" then my understanding is that this is effectively the empty set (are there parts we legitimately think are ready?).

Maybe that means eventing would share the "1.0" designation by association, but its entire featureset would remain alpha, which seems to send a mixed message (e.g. what if I only install eventing?).

[rgregg]

I'm starting to have opinions that the problem is deeper than what we're trying to solve here. Looking around, I see there are some projects where there are distinct content sets for "1.0" and "beta" versions, which are kept up-to-date with the content that meets those bars (Microsoft tends to do this).

Another alternative instead of completely separate content is that everything is explicitly called out as being "beta" or nothing (assume this means GA) in the documentation (I see this a lot in Apple's docs).

I think the problem we're discussing here is largely limited to GitHub's representation of a release, which I think is actually less important in the near future than our knative.dev representation of that release, since that's where SEO should be sending new Knative users.

Perhaps we need a more holistic solution that looks at this from an end-user perspective and tries to find a solution that solves the problems they have, vs. just the way we think about versioning our repos.

[duglin]

What if we reduced eventing's v1.0 scope to just the stuff that's ready

If "ready" means "ready for production" then my understanding is that this is effectively the empty set (are there parts we legitimately think are ready?).

Maybe that means eventing would share the "1.0" designation by association, but its entire featureset would remain alpha, which seems to send a mixed message (e.g. what if I only install eventing?).

If that's true then perhaps we need to revisit eventing's plans and rather than continue to add new features we focus on hardening the "core" (whatever that might be) so that we can actually have something to show for all of the hard work being done.

[duglin]

Perhaps we need a more holistic solution that looks at this from an end-user perspective and tries to find a solution that solves the problems they have, vs. just the way we think about versioning our repos.

I think we're hearing this from lots of sides. IMO, trying to pull out one part of Knative (serving) and ship that w/o the rest of Knative is more than a little awkward and people want the grouping. So, let's work on defining what "Knative's GA" goals are across all repos and shoot for that. Then we can spend time working on meeting that goal instead of discussing how to play with optics.

For example, @mattmoor has the "Serving GA Goals" doc, but perhaps we need a "Knative GA Goals" doc that can describe what end users should be able to do across all components, not just within one of them.

[pmorie]

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?

[pmorie]

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)

[pmorie]

What semVer would a patch release have?

[pmorie]

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

[RichieEscarez]

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"
	---

[pmorie]

I believe this is defunct and will be re-written rather than mutated.