Phasing out Beta from Versioning Guide

[robscott]

What type of PR is this?
/kind documentation

What this PR does / why we need it:
This is a long overdue follow up from my original proposal to phase out beta from Gateway API versioning. Earlier this year, we presented this idea to SIG Network (Jan 19), Gateway API (Jan 23 and Aug 21), and SIG Architecture (Jan 26) meetings. In all cases, I believe we had consensus to move forward with this approach, I just needed to translate the proposal into reality.

With the upcoming v1.0 release of Gateway API, the time has come to define exactly how our versioning policy will work with GA APIs. As I'm doing that, I'm also taking the opportunity to translate this earlier proposal into reality.

Does this PR introduce a user-facing change?:

Gateway API versioning will continue to rely on two release channels - Standard and Experimental. New resources will start in the Experimental Channel with an alpha API Version and then graduate to the Standard Channel with a GA API version. Resources that already have Beta API versions will continue to have them, but no additional Gateway API resources will get a Beta API version.

This is a big change that will have a lasting impact on the API. Asking for lots of reviewers here. As always, please don't hesitate to review if I didn't list you below, trying to not mention too many people here, but everyone's input is appreciated.

/hold for consensus
/cc @arkodg @candita @gcs278 @mlavacca @sunjayBhatia
/assign @shaneutt @youngnick

[k8s-ci-robot]

@robscott: GitHub didn't allow me to request PR reviews from the following users: candita, gcs278.

Note that only kubernetes-sigs members and repo collaborators can review this PR, and authors cannot review their own PRs.

In response to this:

What type of PR is this?
/kind documentation

What this PR does / why we need it:
This is a long overdue follow up from my original proposal to phase out beta from Gateway API versioning. Earlier this year, we presented this idea to SIG Network (Jan 19), Gateway API (Jan 23 and Aug 21), and SIG Architecture (Jan 26) meetings. In all cases, I believe we had consensus to move forward with this approach, I just needed to translate the proposal into reality.

With the upcoming v1.0 release of Gateway API, the time has come to define exactly how our versioning policy will work with GA APIs. As I'm doing that, I'm also taking the opportunity to translate this earlier proposal into reality.

Does this PR introduce a user-facing change?:

Gateway API versioning will continue to rely on two release channels - Standard and Experimental. New resources will start in the Experimental Channel with an alpha API Version and then graduate to the Standard Channel with a GA API version. Resources that already have Beta API versions will continue to have them, but no additional Gateway API resources will get a Beta API version.

This is a big change that will have a lasting impact on the API. Asking for lots of reviewers here. As always, please don't hesitate to review if I didn't list you below, trying to not mention too many people here, but everyone's input is appreciated.

/hold for consensus
/cc @arkodg @candita @gcs278 @mlavacca @sunjayBhatia
/assign @shaneutt @youngnick

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[gcs278]

Looks good to me. I just have some nit picks.

[kflynn]

This looks great, @robscott -- I have a question and I agree with the two nits @gcs278 pointed out, but I'm approving anyway because those could be tackled in a followon PR.

[mlavacca]

is !!! note intended to be as it is? I see no fancy markdown stuff being rendered.

[youngnick]

Yeah, it's rendered in the deploy preview - this is a directive to mkdocs, not a standard Markdown one.

[robscott]

Thanks everyone for the feedback! I think I've addressed everything, PTAL.

[mlavacca]

Looks great to me!

[mikemorris]

I think this change makes sense as we approach GA (where users should be able to expect the CRDs commonly installed by default to be stable and to not have breaking changes) and will help reduce the combinatorial complexity of understanding how release channels interact with API resource versioning.

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kflynn, mikemorris, mlavacca, robscott, sunjayBhatia

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

The pull request process is described here

Needs approval from an approver in each of these files:

• geps/OWNERS [robscott]
• site-src/OWNERS [robscott]

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

[robscott]

Thanks everyone for the feedback! I think I've resolved everything now, PTAL.

[robscott]

I think we've got enough consensus here, going to remove the hold so the next LGTM merges this.

/hold cancel

[youngnick]

/lgtm