diff --git a/docs_dev/releasing.md b/docs_dev/releasing.md index d37e6543b3d..ac3ab178587 100644 --- a/docs_dev/releasing.md +++ b/docs_dev/releasing.md @@ -19,13 +19,12 @@ - [Add new KfDef for the Release](#add-new-kfdef-for-the-release) - [Build and Upload KFCTL Binaries](#build-and-upload-kfctl-binaries) - [Version the website](#version-the-website) - - [Lifcycle](#lifcycle) - - [Updating version numbers etc for the upcoming release (major, minor, or patch)](#updating-version-numbers-etc-for-the-upcoming-release-major-minor-or-patch) - - [Creating and publishing a website branch for v.X.Y](#creating-and-publishing-a-website-branch-for-vxy) + - [Lifecycle](#lifecycle) + - [Creating and publishing a website branch for vX.Y](#creating-and-publishing-a-website-branch-for-vxy) + - [Deploy new branch to Netlify](#deploy-new-branch-to-netlify) + - [Some notes about Kubeflow's Netlify Setup](#some-notes-about-kubeflows-netlify-setup) - [Archiving docs](#archiving-docs) - [Changing the version `www.kubeflow.org` points to](#changing-the-version-wwwkubefloworg-points-to) - - [Some notes about Kubeflow's Netlify Setup](#some-notes-about-kubeflows-netlify-setup) -- [Update the changelog](#update-the-changelog) - [Get Votes for the Release](#get-votes-for-the-release) @@ -201,23 +200,20 @@ Alternatively you can use the UI. # Version the website -The main Kubeflow website at [www.kubeflow.org](www.kubeflow.org) points to the -version of the website we want users to see. - -* Most of the time this will correspond to the **master** branch of the `kubeflow/website` repo - -* However, leading up to a minor release (vX.Y) [www.kubeflow.org](www.kubeflow.org) - will point at a branch containing a stable version of the docs corresponding to vX.Y +The main Kubeflow website at [www.kubeflow.org](www.kubeflow.org) points to the latest change of +[kubeflow/website](https://github.com/kubeflow/website) for most recent Kubeflow and individual +components' guides. For each minor (vX.Y) release, we also publish a corresponding version of the website. Each version of the website is generated from a separate [branch](https://github.com/kubeflow/website/branches) -of the `kubeflow/website` repository. +of the `kubeflow/website` repository. And you can view versioned documentation from the website's +[top bar](https://user-images.githubusercontent.com/37026441/137779544-dbf6b689-e6d8-43e6-9b31-a05c0502c464.png). -* The naming convention is as follows: +The naming convention is as follows: The site at `vX-Y.kubeflow.org` points to the release at vX.Y-branch. For example, the [documentation for v0.6](https://v0-6.kubeflow.org) is -maintained in the +maintained in the branch called [v0.6-branch](https://github.com/kubeflow/website/tree/v0.6-branch). ## Lifecycle @@ -225,51 +221,29 @@ maintained in the Our typical process when getting ready to do a minor release vX.Y (i.e. going from vX.Y to vX.Z); this process doesn't apply for patch releases. -1. Follow the [instructions below](#create-website-branch) to create a release branch for vX.Y -1. Update `www.kubeflow.org` to point at the vX.Y branch ([see below](#update-kubeflow-org)) +1. Follow the [Create website branch instructions](#create-website-branch) to create a release branch for vX.Y. + +1. Follow the [Deploy to Netlify instructions](#deploy-to-netlify) to set up a versioned documentation on Kubeflow website. + 1. Develop vX.Z docs on the master branch - - * Follow the [instructions](#prepare-docs) below to update version numbers etc. on master for the upcoming vX.Z release * Docs for the master branch should be available on [https://master.kubeflow.org](https://master.kubeflow.org) -1. When we are ready to publish docs for vX.Z, follow the [instructions](#update-kubeflow-org) below to - point [www.kubeflow.org](https://www.kubeflow.org) at the master branch +1. Follow the [Archive Instructions](#archive) to mark the docs on the vX.Y branch as archived -1. Follow the [instructions](#archive) to mark the docs on the vX.Y branch as archived +Other guides: - -## Updating version numbers etc for the upcoming release (major, minor, or patch) +* If we ever need to update the default website version, follow the [Production branch instructions](#update-kubeflow-org) + below to point [www.kubeflow.org](https://www.kubeflow.org) to the desired branch. -We usually start updating the website for the upcoming major/minor release when -we've released a good RC for that release. At this point, it's useful for -users to start experimenting with the upcoming release. +* There are [old instructions](https://github.com/kubeflow/kubeflow/issues/6199) which have been out-of-date, but keeping a link here in case we need it in the future. -When we're ready to start updating the docs for the upcoming version, we -need to update various version numbers on the website, to ensure users are -getting the correct installation instructions etc. Here are the steps to follow: -1. Make sure the website branch for the current major/minor version has been - created. For example, if we are working towards release v0.7 then make sure - the website branch for v0.6 exists. - If not, create the branch now before updating any docs for the - upcoming version. See [below](#create-website-branch). + +## Creating and publishing a website branch for vX.Y -1. Edit the version numbers in the site configuration file: - * Edit [config.toml](https://github.com/kubeflow/website/blob/master/config.toml). - * Update the parameters that set the version number for various purposes. - For example, if the upcoming release is Kubeflow v0.7: - ``` - version_menu = "v0.7" - version = "v0.7" - ``` - - * Update the GitHub branch number. For example, if the upcoming release is - Kubeflow v0.7: - ``` - githubbranch = "v0.7-branch" - ``` +1. Create a new section (vX.Y) for dropdown in `config.toml` ([example PR](https://github.com/kubeflow/website/commit/1deed4b4f7846d5c791350620d298a38ce906f1e#)). 1. Update the shortcode that holds the latest Kubeflow version: @@ -281,53 +255,6 @@ getting the correct installation instructions etc. Here are the steps to follow: v0.7.0 ``` -1. Update **all** the shortcodes that hold the config file names and URIs - for the KFDef YAML files - for every platform. For example: - - * Update the GCP IAP config file name in [config-file-gcp-iap.html](https://github.com/kubeflow/website/blob/master/layouts/shortcodes/config-file-gcp-iap.html). - ``` - kfctl_gcp_iap.0.7.0.yaml - ``` - - * Update the GCP IAP config URI in [config-uri-gcp-iap.html](https://github.com/kubeflow/website/blob/master/layouts/shortcodes/config-uri-gcp-iap.html). - ``` - https://raw.githubusercontent.com/kubeflow/manifests/v0.7-branch/kfdef/kfctl_gcp_iap.0.7.0.yaml - ``` - - * And so on, for all the `config-uri-xxx.html` and `config-file-xxx.html` - shortcodes for AWS, kfctl_k8s_istio, kfctl_existing_arrikto, and more. - -1. Update the matrix of Kubernetes versions on - [the Kubernetes overview](https://www.kubeflow.org/docs/started/k8s/overview/). - -1. Update the application version matrix on the [version policy page](https://github.com/kubeflow/website/edit/master/content/docs/reference/version-policy.md) - - * There are a number of different ways to get the application versions - - 1. You can look at the [kustomization.yaml](https://github.com/kubeflow/manifests/blob/30b666f2b8a0d1b5217a095cfe18f6a03f22231f/metadata/overlays/application/kustomization.yaml#L10) - file at the label `app.kubernetes.io/version` - - * TODO(https://github.com/kubeflow/testing/issues/600): Create a script to get all application - version - - 1. You can get the application versions in a running Kubeflow deployment by doing - - ``` - kubectl -n kubeflow get applications - ``` - - * You can use one of the [auto-deployed clusters](https://kf-ci-v1.endpoints.kubeflow-ci.cloud.goog/auto_deploy/) - -1. Add outdated banner to documentation that hasn't been updated recently - - * Run [this script][outdated-script] from within the `website` repository to add the - outdated banner - -[outdated-script]: https://github.com/kubeflow/website/blob/master/scripts/add_outdated_banner.py - - -## Creating and publishing a website branch for vX.Y - 1. Create a new version branch under the [website repository](https://github.com/kubeflow/website). The branch name should have the following format: `v${MAJOR}.${MINOR}-branch`, where @@ -336,6 +263,9 @@ getting the correct installation instructions etc. Here are the steps to follow: [creating branches in your repo](https://help.github.com/en/articles/creating-and-deleting-branches-within-your-repository).) +1. In `vX.Y-branch`, change `version_menu`, `version` and `githubbranch` to the corresponding vX.Y branch + value ([example PR](https://github.com/kubeflow/website/commit/2d1577c51a420b11e9de1116fb024f1fa4f9d7ea#diff-28043ff911f28a5cb5742f7638363546311225a63eabc365af5356c70d4deb77)). + 1. Netlify should auto deploy this branch once its created (see [Branch Deploys](https://docs.netlify.com/site-deploys/overview/#branch-deploy-controls)) @@ -346,14 +276,23 @@ getting the correct installation instructions etc. Here are the steps to follow: * You can check under deploys to see if Netlify deployed it * If no deploys show up you can push a commit to the branch to trigger a deploy + + +## Deploy new branch to Netlify + +Note: Contact [Kubeflow admins](https://groups.google.com/a/google.com/g/google-kubeflow-admins) with the link to this section when we want to cut a new version for Kubeflow website in Netlify. + +Admins use Netlify manage branches for Kubeflow website hosting and update the default branch if needed. Kubeflow Admins need permission to Netify project, and `kubeflow-dns` GCP project. + + 1. Set up DNS for the new site: * In [Cloud DNS](http://console.cloud.google.com/net-services/dns/zones?project=kubeflow-dns&organizationId=714441643818), select the `kubeflow.org` zone. * Create a new CNAME record set for `v${MAJOR}-${MINOR}-branch.kubeflow.org`, pointing - to the new site (`something-something.netlify.com`), with TTL of 5 minutes. + to the new site (`something-something.netlify.com`), with TTL of 5 minutes. Canonical name: ${BRANCHNAME}--competent-brattain-de2d6d.netlify.com. (Example: v0-7-branch--competent-brattain-de2d6d.netlify.com) **Note:** The version format in the URL is different from that in the GitHub branch name! The URL has a **dash** between major and minor version. - For example: `v0-6.kubeflow.org`. + For example: `v0-6.kubeflow.org`. 1. Wait for the DNS record to propogate. You can use `nslookup` to check this. @@ -371,20 +310,34 @@ getting the correct installation instructions etc. Here are the steps to follow: ``` 1. At this point you should be able to access the branch at `https://${BRANCHNAME}.kubeflow.org` but - you will get an ``NET::ERR_CERT_COMMON_NAME_INVALID` SSL certificate error + you will get an `NET::ERR_CERT_COMMON_NAME_INVALID` SSL certificate error * You should be able to proceed through to see the site but you may need to be incognito mode 1. File a support request with Netlify to fix the SSL certificate - * The [external DNS docs](https://community.netlify.com/t/common-issue-how-to-use-netlify-s-branch-deploy-feature-without-netlify-dns/128) + * The [external DNS docs](https://community.netlify.com/t/common-issue-how-to-use-netlify-s-branch-deploy-feature-without-netlify-dns/128) (Step #4) say to file a support request to fix the domain to work with branch deploys when - using external DNS + using external DNS. + * You can use this [Sample ticket](https://user-images.githubusercontent.com/37026441/137782296-87b34da9-a574-4e30-8b5a-474812db579e.png) to describe the SSL certificate update request. + +### Some notes about Kubeflow's Netlify Setup + +* We use external DNS (Cloud DNS); we do not use Netlify DNS + +* We have an A record to redirect kubeflow.org to Netlify + * Ref [kubeflow/website#5](https://github.com/kubeflow/website/issues/5#issuecomment-389037774) + original setup of Netflix + +* We use CNAME records to map `v${MAJOR}-${MINOR}-branch.kubeflow.org` to + `{BRNACHNAME}---competent-brattain-de2d6d.netlify.com` + + ## Archiving docs -When the website branch exists for the previous version of the docs (vX.X) and www.kubeflow.org is pointing to the new version (vX.Y), we must mark the docs for vX.X as being archived and point users at the docs for vX.Y. +When the website branch exists for the previous version of the docs (vX.X) and www.kubeflow.org has released a new version (vX.Y), we must mark the docs for vX.X as being archived. 1. On the branch corresponding to vX.X 1. In the `config.toml` for the **version branch**, @@ -397,42 +350,23 @@ When the website branch exists for the previous version of the docs (vX.X) and w an archived version. 1. Create a PR for the above update, setting the **base branch** in the PR - to the **version** branch (not **master**). Then request a review and merge + to the vX.X's **version** branch (not **master**). Then request a review and merge the PR. + ## Changing the version `www.kubeflow.org` points to -1. In netlify select Build & Deploy -> Deploy Contexts -1. Click Edit Settings -1. Change the production branch to the branch to surface -1. Redeploy both branches - +1. In Netlify, select `www.kubeflow.org` site: https://app.netlify.com/sites/competent-brattain-de2d6d/overview. +1. Select `Site settings` +1. Select `Build & deploy` +1. Find the section called `Branches` +1. Click `Edit settings` +1. Change the `Production branch` to the branch to surface by default. +1. (Optional) Redeploy both branches * You can trigger a redeploy by pushing commits to the branches -## Some notes about Kubeflow's Netlify Setup - -* We use external DNS (Cloud DNS); we do not use Netlify DNS - -* We have an A record to redirect kubeflow.org to Netlify - * Ref [kubeflow/website#5](https://github.com/kubeflow/website/issues/5#issuecomment-389037774) - original setup of Netflix - -* We use CNAME records to map `v${MAJOR}-${MINOR}-branch.kubeflow.org` to - `{BRNACHNAME}---competent-brattain-de2d6d.netlify.com` - - -# Update the changelog - -1. After the release branch is created run the following script to update the changelog - - ``` - update-changelog.sh - ``` - -1. Create a PR with the resulting changes. -1. Repeat above steps as new release candidates are created # Get Votes for the Release