Cluster-api: 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 https://github.com/kubernetes-sigs/cluster-api/pull/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 https://github.com/kubernetes/community/issues/3454#issuecomment-484534141 for the complete instructions.

[detiber]

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

[detiber]

Netlify config update here: https://github.com/kubernetes-sigs/cluster-api/pull/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 https://github.com/kubernetes/k8s.io/pull/318#discussion_r305531482 and be done once and for all. @vincepri, @detiber, WDYT?

[vincepri]

What about naming the subdomain v1alpha1 instead of v0-1?

[detiber]

@vincepri The issue is less about the subdomain used for the redirects and CNAME entries, and more about the name of the underlying branch name (that is the target of the redirects).

[detiber]

I'm not sure how the k8s docs are handling the redirects, I'm not seeing anything related to it in the release-1.15 branch netlify config for example: https://github.com/kubernetes/website/blob/release-1.15/netlify.toml

[detiber]

It looks like some of it is abstracted away in the hugo config: https://github.com/kubernetes/website/blob/release-1.15/config.toml

[detiber]

Aha, I think I cracked the code, it looks like Netlify might just replace . with -: https://release-0-1--kubernetes-sigs-cluster-api.netlify.com/

[davidewatson]

🙃okay! So we can keep the branch names... Do we want to deploy all branches? I think so...

[detiber]

+1 to all branches

[detiber]

Created PRs to fix the netlify URL: https://github.com/kubernetes-sigs/cluster-api/pull/1204 and https://github.com/kubernetes/k8s.io/pull/323

@davidewatson With that I believe we can delete the Netlify configurations for release-01 and v1alpha1 and also delete the release-01 branch.

[detiber]

@davidewatson I believe the Assigning a custom domain steps need to be performed within the Netlify config, and may require some additional trickery as described here: https://community.netlify.com/t/common-issue-how-to-use-netlify-s-branch-deploy-feature-without-netlify-dns/128

[davidewatson]

Thanks Jason, I’ll take a look tonight.

[vincepri]

This should be implemented and ready to go, @detiber do you think we can close this one out?

[detiber]

Yes, let's close
/close

[k8s-ci-robot]

@detiber: Closing this issue.

In response to this:

Yes, let's close
/close

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.