Refactor api-versioning.md Developer doc

[JeromeJu]

Changes

This commit refactors the api-versioning.md developer doc which
previously mixed API versioning and feature versioning. The API-driven
feature versioning was mingled with the process of adding a new CRD
apiVersion.

To have better clarification of the difference between API versioning
and the feature versioning, a new Markdown file feature-versioning is
introduced in light of TEP-0138.

/kind documentation
part of #6965

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has Docs if any changes are user facing, including updates to minimum requirements e.g. Kubernetes version bumps
• [n/a] Has Tests included if any functionality added or changed
• Follows the commit message standard
• Meets the Tekton contributor standards (including functionality, content, code)
• Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
• [n/a] Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings). See some examples of good release notes.
• [n/a] Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

NONE

[QuanZhang-William]

Thanks @JeromeJu for the update. seems like this is a prerequisite to #7090?

Did you consider combining the 2 PRs, I feel the change in this PR is not really a complete story of it?

[QuanZhang-William]

Is there really a point to differentiate the 2 types of feature in the context of per feature flag as eventually all the features will be using individual feature flag (so that you don't really need 2 separate subsetions below)?

I uderstand that enable-api-field will still exist for a while during the migration phase, maybe that is worth mentioning the behavior during & after migration.

[JeromeJu]

Thanks for the suggestion. Yeah eventually we are going to switch to all dedicated feature flag(NOTE not all will be behind Per-feature flag, for example, some behavioural feature flag would need different values, which is not the same as Per-feature flag i.e. largerResult could take different values instead of true/false) for all new features. But the existing features, which is a combinations of behavioural and API-driven features controlled by enable-api-fields will persist for at least ~1 deprecation cycle.

I think it is reasonable to keep the section of behavioural features since they were once the missing pieces in the documentations. And their validations are actually different from Per-feature flags. WDYT?

[QuanZhang-William]

Sure, I'm ok to break down it to 2 types, and there is an "API-driven Features" subsection. However, I believe users are natuarlly looking for the "behaviour features" section but is missing. As a user I would assume all the content in the "API-driven Features" subsection does not apply to "behaviour features", but there are quite some similarities.

In general I think it makes more sense to complete this module in 1 PR, but I'm ok if you are going to add the missing content in the followup PRs to complete structure of this file.

[JeromeJu]

TY for the review. I agree with you that users would also like to see a section of behavioural features. Removed the part about behavioural flags since this is just a doc cleanup, avoiding confusions.

As a user I would assume all the content in the "API-driven Features" subsection does not apply to "behaviour features", but there are quite some similarities.

Would you mind clarifying what are the similarities. Is it that both of them(behavioural features & new features using per-feature flag) would use a dedicated feature flag?

[JeromeJu]

Thanks for the review @QuanZhang-William !
This is a cleanup of docs before introducing the docs in #7090. There were some updates mingled in this PR which I've removed in the update.

I'm happy to combine this in #7090 if that works better for the context. TY!

[QuanZhang-William]

Thanks for the PR! Gonna approve it and let more people review!

[tekton-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: QuanZhang-William, Yongxuanzhang

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:

• OWNERS [Yongxuanzhang]

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

[JeromeJu]

Given second thought, I've noticed the confusion there might be for adding the explanation of behavioural flags in this PR. So I removed the part mentioning behavioural flags to avoid being misleading. While this PR mainly serves as a doc cleanup, I have updated the issue tracking this #6965 (comment) instead.

Also I've tried to combine this PR in #7090 . (let's see if this or the original gets in first)

Thanks to the reviews/comments from @QuanZhang-William for letting me understand such potential confusions.

[tekton-robot]

@JeromeJu: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-tekton-pipeline-go-coverage	98c33d4	link	false	/test pull-tekton-pipeline-go-coverage

Full PR test history. Your PR dashboard.

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. I understand the commands that are listed here.

[JeromeJu]

Closing this as #7090 has already been merged.