This is a Feature Request

What would you like to be added

Compare Docs Intermediate "Work from a local clone" with Community GitHub workflow. Determine if content from Community should be added to Intermediate. One thing I noted is the Community page has a paragraph about NOT using git pull to update your local branch.
https://kubernetes.io/docs/contribute/intermediate
https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md

For example, the Community guide recommends cloning your fork whereas Intermediate recommends cloning kubernetes/website. I tested both workflows with the prereq that I accidentally permanently deleted my local directories and therefore needed to checkout the branch changes I had pushed to my fork. When I followed the steps on Intermediate and then tried to checkout an existing branch, git couldn’t find the branch; but when I followed the steps in contrib page, I could check out the existing branch.

Another difference: the workflow for keeping your fork master branch in sync with kubernetes/website master differs between the two pages, and Intermediate differs from what my new SIG Docs peeps told me.
What I've been told:

git checkout master
git fetch origin
git fetch upstream
git merge upstream/master
git push -f origin

The Contributor guide advocates origin:remote sync using:

git fetch upstream
git checkout master
git rebase upstream/master

The Intermediate page states:

git fetch upstream
git fetch origin

I don't think either of the documented approaches actually updates a contributor's fork master branch. Github advocates the approach told to me via Slack.

I'd like to see a specific sections in Intermediate about:

• Keeping your fork master up-to-date with kubernetes/website master; https://help.github.com/en/articles/syncing-a-fork
• Squashing commits (k8s policy) and link to git info (see Community page)

Also check the Start contributing/Improve existing content section to see if more info is needed, such as squashing commits, which you have to do from command line.

Why is this needed
Make the contribution process as easy as possible for people new to GitHub. Many folks may be familiar with the branch-only git/gerrit workflow like I was, and switching to the GitHub workflow requires an extra step.

Comments