Decide on a documentation versioning/scheme

[moshloop]

What is the planned approach for handling documentation re v1alpha1 vs v1alpha2? I see a couple of potential approaches:

1. Have a different documentation site for each version, similar to k/k
2. Have 1 documentation site focusing on master, and just highlighting version specific differences
3. Have 1 documentation site with a common, v1alpha1 and v1alpha2 sections

@davidewatson @vincepri @ashish-amarnath @detiber @rudoi

My vote is for option 2 until we reach beta and then switch to option 1.

[moshloop]

/kind documentation

[detiber]

My preference is to have a documentation site for each version, since v1alpha2 will differ significantly from v1alpha1. We can leverage the Netlify integration that we have currently in the following ways to handle this:

• enable per-branch subdomains in Netlify
• add a Netlify a new config to the release-0.1 branch
• Add a header to the docs in master to indicate that they are under heavy development and link to v1alpha1 docs.

[moshloop]

I am happy with that as well, who has the rights to create the new subdomain?

[detiber]

I'll work on following up with @davidewatson on this
/assign
/assign @davidewatson

[davidewatson]

I have enabled per branch netlify deployments and am using #1156 to test.

[davidewatson]

The URL for the release-0.1 branch should be https://release-0.1--kubernetes-sigs-cluster-api.netlify.com/. I think we just need to configure a CNAME and update the netlify.toml now. See kubernetes/community#3454 (comment) for the complete instructions.

[detiber]

I went ahead and created the PR for the DNS subdmain here: kubernetes/k8s.io#318
I'll work on creating a PR to update the Netlify config.

[detiber]

Netlify config update here: #1176

[davidewatson]

For some reason the branch name release-0.1 is causing problems. I think it's the dot and the DNS haiku is right. Either way, here's where we are:

• Netlify deployment contexts are configured for branches named: release-0.1, release-01, and v1alpha1.

• A release-01 branch was created from release-0.1 and is correctly served from https://release-01--kubernetes-sigs-cluster-api.netlify.com/

What do we think about renaming the release-0.1 branch to something which is a single valid subdomain?

[davidewatson]

Maybe the right thing to do is just enable all branches and then configure the netlify.toml with redirects for v0-1.docs.cluster-api.k8s.io, etc. Then we can update kubernetes/k8s.io per kubernetes/k8s.io#318 (comment) and be done once and for all. @vincepri, @detiber, WDYT?