Add in the contribution guide purpose of versions

[camilamacedo86]

Currently, we have:

• the PROJECT version (v1,v2,v3)
• the release CLI version (1.0.0, 2.0.0)
• and now we will have the plugin's version (dir V2 and 2.0.0)

This task is for we clarify its purpose and how to work with them. This section should address the answer for questions such as: When should I as a contributor bump a new plugin version or not? When should I as contributor create a v3 plugin dir? When should I as a contributor create a new project version/? Can an introduce a breaking change for a stable VX project version?

[camilamacedo86]

/kind documentation

[estroz]

Summary from kubebuilder/controller-runtime/controller-tools biweekly meeting today:

• Configuration (PROJECT file) version was used to inform on scaffolding version up to and including version: "2". Now configuration version only informs on the configuration spec.
  • Only changes to this spec will merit a configuration version bump.
• Plugin version, ex. the semver in key go.kubebuilder.io/v2.0, informs on the scaffolding version was used to run init, create api, or create webhook. This version, in the form of a full plugin key, is recorded in the layout configuration field.
  • Changes to the set of scaffolded files will result in either a major or minor version bump in accordance with a plugin versioning spec (TBD).
  • Patch version will be dropped from versions since it doesn't conform to the concept a scaffolding change: either a scaffold change breaks previous versions or does not.
• kubebuilder binary version is unrelated to both configuration and plugin version.
  • When either a configuration or plugin version bumps major versions, a new binary release must be made.
  • More than one version for a given plugin will be allowed so users do not have to upgrade on each plugin version change. For example: kubebuilder binary version v3.0.0 will support projects with a PROJECT file containing one of the following layout values:
    • go.kubebuilder.io/v2.0
    • go.kubebuilder.io/v2.1
    • go.kubebuilder.io/v3.0
  • Migration guides will be written for changes warranting version bumps.

Some open questions:

• How do we determine if a plugin change warrants a major, a minor, or no version bump?
  • This needs to be codified in a versioning spec.
• The binary will be bumped to a new major version if there is a configuration version bump. Will a major binary version bump also occur if a plugin's major version is bumped?
  • This can get tricky if we have more than one plugin.
• Will the binary auto-upgrade the minor version value of a plugin found in layout if the binary supports a greater minor version?
• (Suggestion) should kubebuilder adopt a migration guide generator like that in the Operator SDK to make migration doc writing a requirement with per-PR granularity?

I may have forgotten or misremembered a few things so please feel free to clarify.

/cc @DirectXMan12 @mengqiy @joelanford @camilamacedo86

/priority important-soon
/milestones v3.0.0

[camilamacedo86]

Missing just add that until we support v2 projects and have v2 code in the project then, new major bump plugins versions ( breaking changes ) cannot affect the V2 projects.

I will get this one and try to come up with simplified info in the Contribution Guide and then, we can discuss the open questions in the pr as well. I will need your collab pals with to review and help me shape that :-)

/assign @camilamacedo86

[camilamacedo86]

Hi @estroz @joelanford,

I forget to put a hold in the doc and it gets merged after a few reviews. We can do a follow up as well as always.

I will re-open the issue for you are both are able to check and let us know if you think that still something that needs to be addressed here.

/reopen

[k8s-ci-robot]

@camilamacedo86: Reopened this issue.

In response to this:

Hi @estroz @joelanford,

I forget to put a hold in the doc and it gets merged after a few reviews. We can do a follow up as well as always.

I will re-open the issue at for you are both are able to check and let us know if you think that still something that needs to be addressed here.

/reopen

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.

[camilamacedo86]

/assign @estroz
Since has been working on in it.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[camilamacedo86]

/remove-lifecycle stale

It still required. we need to fix the context after its changes definitions.
Also, it shows a need for a milestone v3.0.0