Website: [Release 1.1] Release Website 1.1

[jlewi]

Opening this issue to track doing a release of the website for Kubeflow 1.1

• We still need to find an owner to drive this (see kubeflow/kubeflow#5022)

• The first step is cutting a 1.0 branch from master providing a stable link to the docs so we can begin updating the docs on master.

• Docs for versioning the website: https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#version-the-website

[issue-label-bot[bot]]

Issue-Label Bot is automatically applying the labels:

| Label | Probability |
| ------------- | ------------- |
| area/docs | 1.00 |
| kind/feature | 0.73 |

Please mark this comment with :thumbsup: or :thumbsdown: to give our bot feedback!
Links: app homepage, dashboard and code for this bot.

[jlewi]

It looks like we might want to branch 1.0 on
https://github.com/kubeflow/website/tree/61b5ed89590fe961c26d18da30969f3841dbf93a

After that it looks like we start getting commits related to 1.1

[RFMVasconcelos]

Hi Jeremy,

As soon as I get access to the repo I'll push that branch up.

As far as netlify, is that automatic or are there any additional steps?

[jlewi]

@RFMVasconcelos

As soon as I get access to the repo I'll push that branch up.

Please read:
https://groups.google.com/forum/#!topic/kubeflow-discuss/pGflW6m9Xrg

And please file PRs.

As far as netlify, is that automatic or are there any additional steps?

Is what automatic?

[RFMVasconcelos]

Hi @jlewi, thank you for the guidance!!

Please read:

I'm going through all the guidelines. Signed CLA, ready to start contributing :)

And please file PRs.

Will do! Started out with this one: https://github.com/kubeflow/website/pull/1999

Is what automatic?

I haven't used netlify before. Was wondering what I needed to know to render the website, or if it was automatic.

[8bitmp3]

Hey @RFMVasconcelos I left some suggestions in your PR https://github.com/kubeflow/website/pull/1999. (I'm not an official editor but a few things may need to be reviewed by you before the official PR review.)

[jlewi]

@RFMVasconcelos The website is automatically updated once PR is merged.

Checkout the quickstart: https://github.com/kubeflow/website#quickstart

When you create a PR it will automatically create preview for you of the rendered website.

[8bitmp3]

@jlewi Will you be open to accepting PRs about streamlining Kubeflow's Getting Started section? I think it was @LyleHenkeman who posted about it here. If you are open to improvements, I can work on it and submit a PR. @LyleHenkeman - I did spend a bit of time working through the steps because I was initially interested in the KF CLI and Pipelines, so I think I get why the current guide is a bit "busy". Cheers

[jlewi]

@8bitmp3 Yes; would you mind opening an issue and maybe outlining your changes before getting started on a PR?

[jlewi]

V1.0-branch has been cut:
https://github.com/kubeflow/website/tree/v1.0-branch
at
https://github.com/kubeflow/website/tree/61b5ed89590fe961c26d18da30969f3841dbf93a

[jlewi]

Next steps is to follow:
https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#creating-and-publishing-a-website-branch-for-vxy

To get the branch deployed

[jlewi]

The deployment on the v1.0-branch is failing.

3:29:00 PM: $ hugo
3:29:01 PM: Building sites …
3:29:02 PM: ERROR 2020/06/16 22:29:02 error: failed to transform resource: POSTCSS: failed to transform "scss/main.css" (text/css): PostCSS not found; install with "npm install postcss-cli". See https://gohugo.io/hugo-pipes/postcss/
3:29:05 PM: Total in 3836 ms
3:29:05 PM: Error: Error building site: logged 1 error(s)
3:29:05 PM: ​
3:29:05 PM: ┌─────────────────────────────┐
3:29:05 PM: │   "build.command" failed    │
3:29:05 PM: └─────────────────────────────┘
3:29:05 PM: ​
3:29:05 PM:   Error message
3:29:05 PM:   Command failed with exit code 255: hugo
3:29:05 PM: ​
3:29:05 PM:   Error location
3:29:05 PM:   In build.command from netlify.toml:
3:29:05 PM:   hugo
3:29:05 PM: ​
3:29:05 PM:   Resolved config
3:29:05 PM:   build:
3:29:05 PM:     command: hugo
3:29:05 PM:     publish: /opt/build/repo/public

[jlewi]

Not sure why that's only happening on the branch. We will need to get that fixed.
Does anyone want to investigate?

[jlewi]

2001 is fixed. v1-0-branch is now serving

https://v1-0-branch--competent-brattain-de2d6d.netlify.app/

There was an existing cname record

For v1.0.kubeflow.org ; it was point at
https://master--competent-brattain-de2d6d.netlify.app/

I updated it to point at the v1-0 branch

There was a cname record for www.kubeflow.org pointing at 0.7; I updated it to point at master.
I'm not sure that CNAME record actually matters.

I think we may need to change netlify to make the 1.0 branch the main branch.

[jlewi]

https://v1-0.kubeflow.org/

Giving a DNS error.
DNS_PROBE_FINISHED_NXDOMAIN

nslookup v1-0.kubeflow.org
Server:     127.0.0.1
Address:    127.0.0.1#53

Non-authoritative answer:
v1-0.kubeflow.org   canonical name = v1-0-branch--competent-brattain-de2d6d.netlify.app/.
Name:   v1-0-branch--competent-brattain-de2d6d.netlify.app/
Address: 23.217.138.110
Name:   v1-0-branch--competent-brattain-de2d6d.netlify.app/
Address: 23.202.231.169

Lets give it a bit more time to propogate

[jlewi]

There is a typo in the CNAME record; there should be a trailing "/" on the value. I fixed that; still waiting for it to propogate.

[jlewi]

curl --insecure https://v1-0.kubeflow.org

Returning 404

[jlewi]

Filed a support request to the certificate updated; still no idea why I'm still getting 404s.

[8bitmp3]

Same, "Not Found".

[jlewi]

The 404 is fixed. Netlify told me that I had the subdomain name wrong; it needs to match the branch name so the cname record needs to be "v1-0-branch"
https://v1-0-branch.kubeflow.org/

This is now accessible but with an SSL error. Will ask Netlify to take care of the certificate

[jlewi]

Certificate should be fixed as well.

[jlewi]

I followed
https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#changing-the-version-wwwkubefloworg-points-to

to change www.kubeflow.org to point at the v1-0-branch

It looks like www.kubeflow.org was still pointing at master; so I triggered a deploy.

Looks like it is now pointing at the v1.0-branch
https://www.kubeflow.org/docs/components/serving/kfserving/#install-with-kubeflow
don't include #1998

Looks like master isn't correct
https://master.kubeflow.org/docs/components/serving/kfserving/#install-with-kubeflow

Looks like its got the 1.0 branch docs and not #1998

https://master--competent-brattain-de2d6d.netlify.app/docs/components/serving/kfserving/#install-with-kubeflow

Also pointing at the old docs. Lets try forcing a commit to master to trigger a redeploy

[jlewi]

I triggered a redeploy of master by pushing a commit and now
https://master.kubeflow.org/docs/components/serving/kfserving/#install-with-kubeflow
includes #1998

[8bitmp3]

Will share a list of proposals soon hopefully (ref: https://github.com/kubeflow/website/issues/1984#issuecomment-644907943) Got Hugo and the doc site working locally.)

[jlewi]

@8bitmp3 You shouldn't really need to run Hugo locally; If you open up a PR a preview will be automatically generated.

[jlewi]

@RFMVasconcelos @8bitmp3 Do you want to take on making some of the changes on master needed to prepare the docs for the 1.1 release?

See for example
https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#updating-version-numbers-etc-for-the-upcoming-release-major-minor-or-patch

[8bitmp3]

@jlewi Has the date for v1.1 been set in stone yet? Cheers

[jlewi]

@8bitmp3 We finalize the RC once its ready. Lets aim for 2 weeks from now.

[jlewi]

@8bitmp3 and @RFMVasconcelos any update on this?

One idea would be to go through and add banners like this one indicating the page is outdated
https://master.kubeflow.org/docs/gke/deploy/delete-ui/

If we could script that and add it to every page; that might not be a bad way to force every page owner to review their docs and update them for 1.1

[8bitmp3]

@jlewi regarding streamlining Kubeflow's Getting Started section

I think it was @LyleHenkeman who posted about it here. ... the current guide is a bit "busy".

I think it's about reducing cognitive overhead.

Although Kubeflow and Kubernetes are not simple, but maybe we can merge a few paragraphs/pages and rework the order of things to decrease UX "friction". I can start a draft PR while @jlewi can review changes as they are implemented. And if you can give some feedback here first before I start, it'll be awesome.

Some of the best installation guides I've used have a sense of flow. You use them once and then, hopefully, never come back.

_1. Consistency in naming 🔀_

In Getting Started, we are greeted with a nice flow chart/diagram (see below) before receiving instructions on what to do next in each of the _three_ installation paths (in green) that cover _four_ potential scenarios.

(I copy-pasted sections - they are in orange and green - from the entire site's Getting Started view to find the corresponding guide per each solution (blue).)

In addition, there're links in the menu to the left for each of _three_ installation guides (in orange). And on the right-hand side, there are Docsy-generated (?) subheadings from the "Installing Kubeflow" markdown file:

Because the same things are reworded in different ways, including in the flow chart, this can be a bit confusing, especially for those new to K8s and KF, since you're greeted with all that when you try to figure out how to install.

Descriptions/titles of each of our three installations can be more consistent, so the whole thing is more friendly for the newcomers.

I think this is a small but a significant example of cognitive overload.

_2. Installation steps for KF on an existing cluster 🔀_

Related to @LyleHenkeman's post here.

Notice the flow below.

1. You're in Installing Kubeflow and come across Installing Kubeflow on an existing Kubernetes cluster. Click on the guide to deploying Kubeflow on Kubernetes:

1. This takes you to an Overview of Deployment on Existing Clusters

2. You have to scroll down and inside the last table are the next options (click on one of them):

1. To run KF on K8s with Istio, select Follow instructions: Kubeflow Deployment with kfctl_k8s_istio, which has its own Before you start and other sections.

Note that in Step 4 you should be using kfctl. I assume that the user should have read Installing command line tools back on the Getting Started page.

To sum up, this can definitely be streamlined. I propose to have several sections combined in one Markdown to reduce the number of clicks, so that instead of going back and forth to different pages, it's designed as a one long scrolling page.

Step 3 should visually have a more clear "this is what you should do next options" section, where the options are in a table next to YAML files . But some users may want to know why we have to use YAML and what is Istio, since they are not widely known outside K8s.

Also, we should probably have the same information repeated on different pages, such as Installing command line tools since it's hard to find otherwise (see Step 4).

_3. Installation steps for cloud-based KF ☁️_

Notice the flow below. For example, if you want to get KF up and running on GCP, you are several clicks away from the instructions ("you need to learn to deploy") to look into more options ("which deployment option would you like, we have many"), which means more clicking:

1. Click Cloud Installation:

1. Go to Google Cloud for Kubeflow:

1. You're greeted with a short page that tells you to go to deployment 🙇‍♂️:

1. Then, you're on the deploying page, since installation and deployment mean kind of different things:

Perhaps at least here and elsewhere in the Cloud installation guides we can emphasize that deploying and installing can be the same/different things. And Step 3 is a bit strange - but after a while it makes more sense to have it.

Let me know what you think and I can get started.

[jlewi]

@8bitmp3 That sounds great. My ask is that we create separate issues to discuss specific refactorings. Lets use this issue to track getting the docs ready for 1.1. Streamlining Kubeflow's Getting Started section isn't really blocking that so lets discuss in a separate issue.

[RFMVasconcelos]

Hi @8bitmp3, nice overview! There seems to be space to improve there.

@jlewi I can add the "outdated" banners to every page on the v1.1 branch and submit a PR. What do you think?

[jlewi]

@8bitmp3 responding to your question we could definitely use your help driving the docs for 1.1.

Could you take a look at https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md and see what steps remain?

[RFMVasconcelos]

Hi @8bitmp3 how is progress on this? Would you like some help on my side?

[jlewi]

@8bitmp3 @RFMVasconcelos Any update on this?

[RFMVasconcelos]

Hi @jlewi, so far I've added the "outdated" banners.

@RFMVasconcelos @8bitmp3 Do you want to take on making some of the changes on master needed to prepare the docs for the 1.1 release?

See for example
https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#updating-version-numbers-etc-for-the-upcoming-release-major-minor-or-patch

It seems like this still needs to happen, correct? I am happy to take on parts of this task, though I'd only be able to focus on it from Friday onwards. Would that work?

@8bitmp3

• did you start the release process in any way?
• did you create a new issue for this -> https://github.com/kubeflow/website/issues/1984#issuecomment-652582964.

[8bitmp3]

Hi @8bitmp3 how is progress on this? Would you like some help on my side?

@RFMVasconcelos yes, definitely. Where do we start on the docs site here https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md? I can't see what has been done and what needs to be done, since it's new to me. Also, later on we should probably update the release process overview - it may appear overwhelming or heavy on the cognitive load for new people like me.

did you create a new issue for this -> #1984 (comment).

It's in the works!

[RFMVasconcelos]

I believe @jlewi is counting on the 2 of us to drive this. I'm also new to the system though.

• What would be the best way for us to sync efforts?

[8bitmp3]

Ah, cool @RFMVasconcelos Check your inbox 🙌 cc @jlewi

[RFMVasconcelos]

@8bitmp3 this week's community meeting is at 1:30 am for me, I believe that for you as well.

Next week I'm OOO, which might delay this effort :/

I'd suggest meeting on Monday July 27th -> https://meet.google.com/skg-iebf-kon

I'm available all morning (UK time) or 3pm to 4pm, then only after 6:30pm.

Anyone is welcome to join!

[RFMVasconcelos]

This way we can organize our efforts to roll this out asap 🚀

[8bitmp3]

3pm sounds good! @RFMVasconcelos @jlewi 🚀🙌

[8bitmp3]

@jlewi So, @RFMVasconcelos and I are happy to help with the docs for the Canonical side and other platforms.

ToDo:

• Let's arrange a quick call with @jlewi to understand what needs to be done right now for v.1.1 (in the context of https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#version-the-website) with Jeremy and other product folks, if necessary.
• Timing: unlike the KF community call - let's schedule the Meet for earlier than evening Pacific time, since it's otherwise going to be after midnight for the folks in Europe.
  
  
  
  • Example: 5pm in parts of Western Europe is 9am in California (or 8pm -> 12pm).
  
  

Let's do it 🚀

WDYT?

[jlewi]

hi @RFMVasconcelos @8bitmp3

So the first item would be

Is the doc content up to date? If not can we file P0 bugs against the content project owners?

Looking at https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#version-the-website:

• master.kubeflow.org has been created
• If you look at master.kubeflow.org the version menu is still missing the 1.1 version
  
  
  
  • So we need to follow the instructions to add this
  
  

I think those are the steps remaining to get the docs on master.kubeflow.org up to date. Once they are up to date we can switch over www.kubeflow.org to point to those docs.

[jlewi]

Based on OWNERs: https://github.com/kubeflow/website/blob/162724186116eeeef1cba08d410376baa2debf49/OWNERS#L1
@animeshsingh @rmgogogo @joeliedtke might also be able to help answer questions.

[Jeffwan]

https://github.com/kubeflow/website/issues/2061 Create one issue for AWS. we will finish doc by eod

[adrian555]

Created one PR #2064 to add the operator info

[RFMVasconcelos]

hi @jlewi, @8bitmp3,

I have updated the outdated banners with a new PR -> #2066

I have also updated versioning and added v1.0 to the drop-down menu -> #2067

As for steps 5 & 6 in instructions, I need a bit more guidance on how to update them.

• What are we ready to say about k8s versions and v1.0?

[jlewi]

Thanks @RFMVasconcelos we are testing KF on GKE 1.16 so we can say KF is tested and validated on 1.16. I think I saw some issues saying that 1.18 has issues. For the other versions we can say no known issues.

[Jeffwan]

https://github.com/kubeflow/website/pull/2065 AWS is ready for 1.1 release and please help approve the website change.

@RFMVasconcelos @8bitmp3 @jlewi

[jlewi]

At the meeting we decided we will flip over the website to the 1.1 docs as soon as the KFP docs are updated to reflect multi-user.

@Bobgy Are the docs already updated for multiuser or can we get them updated.

[Bobgy]

I have been writing docs full time in recent days.
I have one more item to finish, it will need 1 day for review. So I am targetting end of this week.

EDIT: tracking issue: https://github.com/kubeflow/pipelines/issues/4317

[8bitmp3]

I understand there're still quite a few moving parts with various stakeholders. I've just reviewed a couple of fairly large PRs (https://github.com/kubeflow/website/pull/2056 and https://github.com/kubeflow/website/pull/2071).

[8bitmp3]

I've also reviewed https://github.com/kubeflow/website/pull/2019 @RFMVasconcelos which is related to another PR of yours.

[Bobgy]

KFP multi-user doc all clear
@jlewi

[jlewi]

• www.kubeflow.org is now pointing at the 1.1 docs
  
  
  
  • e.g https://www.kubeflow.org/docs/gke/deploy/
  
  
• https://v1-0-branch.kubeflow.org/ is pointing to the 1.0 docs

@rui5i @8bitmp3 Now that the 1.0 branch is published we should be able to updown the version selector to include the 1.0 docs. Could one of you please send a PR to do that?

[8bitmp3]

Just reviewed @Bobgy 's PR https://github.com/kubeflow/website/pull/2101 - it's a guide (KF v1.1) on Updating Kubeflow Pipelines deployment on Google Cloud

[8bitmp3]

@rui5i @8bitmp3 Now that the 1.0 branch is published we should be able to updown the version selector to include the 1.0 docs. Could one of you please send a PR to do that?

@jlewi I'm sure @rui5i or I can assist 👍 Can you point us (especially me) to the steps in https://github.com/kubeflow/kubeflow/blob/master/docs_dev/releasing.md#updating-version-numbers-etc-for-the-upcoming-release-major-minor-or-patch ? Thank you for all the help

[jlewi]

@8bitmp3 Its step two updating config.toml

[8bitmp3]

Finished (final) review of KFP installation on kind, k3s and k3s on WSL (Windows) https://github.com/kubeflow/website/pull/2056#pullrequestreview-464291545

[animeshsingh]

@shawnzhu @adrian555 @vpavlin this page might need an update from your perspective
https://www.kubeflow.org/docs/started/getting-started/

[adrian555]

@jlewi and @animeshsingh, do you know who are maintaining the istio and istio-dex? There are not v1.1.0 version for these two. If no plan to maintain a v1.1.0 version, I will have to use a different kfdef for the kfctl guide.

[jlewi]

@adrian555 Primary owners of the istio dex configs should be @krishnadurai and @yanniszark

[jlewi]

@8bitmp3 and @RFMVasconcelos Can we prioritize updating config.toml so the versions drop down shows the link to the 1.0 docs? Right now users can't find the 1.0 docs. Someone is asking about this in slack.

[8bitmp3]

@jlewi 👍 https://github.com/kubeflow/website/pull/2111

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.