From 09e8f829dd531b1a73c04ac08a55abc8a039e0b4 Mon Sep 17 00:00:00 2001
From: Tim Bannister <tim@scalefactory.com>
Date: Tue, 4 Feb 2020 07:25:26 +0000
Subject: [PATCH] Revise pull request template (#18744)

* Revise pull request template

* Reference compiled docs in PR template

Refer readers to https://k8s.io/contribute/start/

This keeps the template short, and it lets Hugo use templating for
the current version.
---
 .github/PULL_REQUEST_TEMPLATE.md    | 37 ++++++++++++++++-------------
 content/en/docs/contribute/start.md | 33 +++++++++++++++++++++----
 2 files changed, 48 insertions(+), 22 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 0f1c347cfcd48..c7040f7fa8133 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,17 +1,20 @@
->^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-> Remember to delete this note before submitting your pull request.
->
-> For pull requests on 1.18 Features: set Milestone to 1.18 and Base Branch to dev-1.18
->
-> For pull requests on Chinese localization, set Base Branch to release-1.16
-> Feel free to ask questions in #kubernetes-docs-zh
->
-> For pull requests on Korean Localization: set Base Branch to dev-1.16-ko.\<latest team milestone>
->
-> If you need Help on editing and submitting pull requests, visit:
-> https://kubernetes.io/docs/contribute/start/#improve-existing-content.
->
-> If you need Help on choosing which branch to use, visit:
-> https://kubernetes.io/docs/contribute/start#choose-which-git-branch-to-use.
->^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
->
+<!-- 🛈
+
+ Hello!
+
+ Remember to ADD A DESCRIPTION and delete this note before submitting
+ your pull request. The description should explain what will change,
+ and why.
+
+ For overall help on editing and submitting pull requests, visit:
+  https://kubernetes.io/docs/contribute/start/#improve-existing-content
+
+ Use the default base branch, “master”, if you're documenting existing
+ features in the English localization.
+
+ If you're working on a different localization (not English), or you
+ are documenting a feature that will be part of a future release, see
+ https://kubernetes.io/docs/contribute/start#choose-which-git-branch-to-use
+ for advice.
+
+-->
diff --git a/content/en/docs/contribute/start.md b/content/en/docs/contribute/start.md
index ff1f62b149b9c..4af5f6d5cefd2 100644
--- a/content/en/docs/contribute/start.md
+++ b/content/en/docs/contribute/start.md
@@ -196,15 +196,38 @@ to base your work on. Use these guidelines to make the decision:
 
 - Use `master` for fixing problems in content that is already published, or
   making improvements to content that already exists.
-  - Use a release branch (such as `dev-{{< release-branch >}}` for the {{< release-branch >}} release) to document upcoming features
-  or changes for an upcoming release that is not yet published.
-- Use a feature branch that has been agreed upon by SIG Docs to collaborate on
-  big improvements or changes to the existing documentation, including content
-  reorganization or changes to the look and feel of the website.
+- Use `master` to document something that is already part of the current
+  Kubernetes release, but isn't yet documented. You should write this content
+  in English first, and then localization teams will pick that change up as a
+  localization task.
+- If you're working on a localization, you should follow the convention for
+  that particular localization. To find this out, you can look at other
+  pull requests (tip: search for `is:pr is:merged label:language/xx`)
+  {{< comment >}}Localization note: when localizing that tip, replace `xx`
+  with the actual ISO3166 two-letter code for your target locale.{{< /comment >}}
+  - Some localization teams work with PRs that target `master`
+  - Some localization teams work with a series of long-lived branches, and
+    periodically merge these to `master`. This kind of branch has a name like
+    dev-\<version>-\<language code>.\<team milestone>; for example:
+    `dev-{{< release-branch >}}-ja.1`.
+- If you're writing or updating documentation for a feature change release,
+  then you need to know the major and minor version of Kubernetes that
+  the change will first appear in.
+  - For example, if the feature gate JustAnExample is going to move from alpha
+    to beta in the next minor version, you need to know what the next minor
+    version number is.
+  - Find the release branch named for that version. For example, features that
+    changed in the v{{< release-branch >}} release got documented in the branch
+    named `dev-{{< release-branch >}}`.
 
 If you're still not sure which branch to choose, ask in `#sig-docs` on Slack or
 attend a weekly SIG Docs meeting to get clarity.
 
+{{< note >}}
+If you already submitted your pull request and you know that the Base Branch
+was wrong, you (and only you, the submitter) can change it.
+{{< /note >}}
+
 ### Submit a pull request
 
 Follow these steps to submit a pull request to improve the Kubernetes