Merge remote-tracking branch 'upstream/master'

8 files changed, 230 insertions, 28 deletions

diff --git a/contributors/design-proposals/autoscaling/vertical-pod-autoscaler.md b/contributors/design-proposals/autoscaling/vertical-pod-autoscaler.md
index 13d235f8..d990d7db 100644
--- a/contributors/design-proposals/autoscaling/vertical-pod-autoscaler.md
+++ b/contributors/design-proposals/autoscaling/vertical-pod-autoscaler.md
@@ -558,7 +558,7 @@ VPA controls the request (memory and CPU) of containers. In MVP it always sets
 the limit to infinity. It is not yet clear whether there is a use-case for VPA
 setting the limit.
 
-The request is calculated based on analysis of the current and revious runs of
+The request is calculated based on analysis of the current and previous runs of
 the container and other containers with similar properties (name, image,
 command, args).
 The recommendation model (MVP) assumes that the memory and CPU consumption are
diff --git a/contributors/design-proposals/multicluster/multicluster-reserved-namespaces.md b/contributors/design-proposals/multicluster/multicluster-reserved-namespaces.md
new file mode 100644
index 00000000..0f664cb2
--- /dev/null
+++ b/contributors/design-proposals/multicluster/multicluster-reserved-namespaces.md
@@ -0,0 +1,51 @@
+# Multicluster reserved namespaces
+
+@perotinus
+
+06/06/2018
+
+## Background
+
+sig-multicluster has identified the need for a canonical set of namespaces that
+can be used for supporting multicluster applications and use cases. Initially,
+an [issue](https://github.com/kubernetes/cluster-registry/issues/221) was filed
+in the cluster-registry repository describing the need for a namespace that
+would be used for public, global cluster records. This topic was further
+discussed at the
+[SIG meeting on June 5, 2018](https://www.youtube.com/watch?v=j6tHK8_mWz8&t=3012)
+and in a
+[thread](https://groups.google.com/forum/#!topic/kubernetes-sig-multicluster/8u-li_ZJpDI)
+on the SIG mailing list.
+
+## Reserved namespaces
+
+We determined that there is currently a strong case for two reserved namespaces
+for multicluster use:
+
+-   `kube-multicluster-public`: a global, public namespace for storing cluster
+    registry Cluster objects. If there are other custom resources that
+    correspond with the global, public Cluster objects, they can also be stored
+    here. For example, a custom resource that contains cloud-provider-specific
+    metadata about a cluster. Tools built against the cluster registry can
+    expect to find the canonical set of Cluster objects in this namespace[1].
+
+-   `kube-multicluster-system`: an administrator-accessible namespace that
+    contains components, such as multicluster controllers and their
+    dependencies, that are not meant to be seen by most users directly.
+
+The definition of these namespaces is not intended to be exhaustive: in the
+future, there may be reason to define more multicluster namespaces, and
+potentially conventions for namespaces that are replicated between clusters (for
+example, to support a global cluster list that is replicated to all clusters
+that are contained in the list).
+
+## Conventions for reserved namespaces
+
+By convention, resources in these namespaces are local to the clusters in which
+they exist and will not be replicated to other clusters. In other words, these
+namespaces are private to the clusters they are in, and multicluster operations
+must not replicate them or their resources into other clusters.
+
+[1] Tools are by no means compelled to look in this namespace for clusters, and
+can choose to reference Cluster objects from other namespaces as is suitable to
+their design and environment.
diff --git a/contributors/devel/api-conventions.md b/contributors/devel/api-conventions.md
index 0243dbd8..7a614fff 100644
--- a/contributors/devel/api-conventions.md
+++ b/contributors/devel/api-conventions.md
@@ -742,7 +742,9 @@ APIs may return alternative representations of any resource in response to an
 Accept header or under alternative endpoints, but the default serialization for
 input and output of API responses MUST be JSON.
 
-Protobuf serialization of API objects are currently **EXPERIMENTAL** and will change without notice.
+A protobuf encoding is also accepted for built-in resources. As proto is not
+self-describing, there is an envelope wrapper which describes the type of
+the contents.
 
 All dates should be serialized as RFC3339 strings.
 
diff --git a/contributors/devel/cri-validation.md b/contributors/devel/cri-validation.md
index 2ca5a0e0..efb98022 100644
--- a/contributors/devel/cri-validation.md
+++ b/contributors/devel/cri-validation.md
@@ -2,19 +2,26 @@
 
 CRI validation testing provides a test framework and a suite of tests to validate that the Container Runtime Interface (CRI) server implementation meets all the requirements. This allows the CRI runtime developers to verify that their runtime conforms to CRI, without needing to set up Kubernetes components or run Kubernetes end-to-end tests.
 
-CRI validation testing is currently Alpha and is hosted at the [cri-tools](https://github.com/kubernetes-incubator/cri-tools) repository. Performance benchmarking will be added in the future. We encourage the CRI developers to report bugs or help extend the test coverage by adding more tests.
+CRI validation testing is GA since v1.11.0 and is hosted at the [cri-tools](https://github.com/kubernetes-incubator/cri-tools) repository. We encourage the CRI developers to report bugs or help extend the test coverage by adding more tests.
 
 ## Install
 
-The test suites can be installed easily via `go get` command:
+The test suites can be downloaded from cri-tools [release page](https://github.com/kubernetes-incubator/cri-tools/releases):
 
 ```sh
-go get github.com/kubernetes-incubator/cri-tools/cmd/critest
+VERSION="v1.11.0"
+wget https://github.com/kubernetes-incubator/cri-tools/releases/download/$VERSION/critest-$VERSION-linux-amd64.tar.gz
+sudo tar zxvf critest-$VERSION-linux-amd64.tar.gz -C /usr/local/bin
+rm -f critest-$VERSION-linux-amd64.tar.gz
 ```
 
-Then `critest` binary can be found in `$GOPATH/bin`.
+critest requires [ginkgo](https://github.com/onsi/ginkgo) to run parallel tests. It could be installed by
 
-*Note: ensure GO is installed and GOPATH is set before installing critest.*
+```sh
+go get -u github.com/onsi/ginkgo/ginkgo
+```
+
+*Note: ensure GO is installed and GOPATH is set before installing ginkgo.*
 
 ## Running tests
 
@@ -25,7 +32,7 @@ Before running the test, you need to _ensure that the CRI server under test is r
 ### Run
 
 ```sh
-critest validation
+critest
 ```
 
 This will
@@ -34,15 +41,13 @@ This will
 - Run the tests using `ginkgo`
 - Output the test results to STDOUT
 
-critest connects to `/var/run/dockershim.sock` by default. For other runtimes, the endpoint can be set in two ways:
-
-- By setting flags `--runtime-endpoint` and `--image-endpoint`
-- By setting environment variables `CRI_RUNTIME_ENDPOINT` and `CRI_IMAGE_ENDPOINT`
+critest connects to `unix:///var/run/dockershim.sock` by default. For other runtimes, the endpoint can be set by flags `-runtime-endpoint` and `-image-endpoint`.
 
 ## Additional options
 
-- `--focus`, `-f`: Only run the tests that match the regular expression.
-- -`-ginkgo-flags`, `-g`: Space-separated list of arguments to pass to Ginkgo test runner.
-- `--image-endpoint`, `-i`: Set the endpoint of image service. Same with runtime-endpoint if not specified.
-- `--runtime-endpoint`, `-r`: Set the endpoint of runtime service. Default to `/var/run/dockershim.sock`.
-- `--skip`, `-s`: Skip the tests that match the regular expression.
+- `-ginkgo.focus`: Only run the tests that match the regular expression.
+- `-image-endpoint`: Set the endpoint of image service. Same with runtime-endpoint if not specified.
+- `-runtime-endpoint`: Set the endpoint of runtime service. Default to `unix:///var/run/dockershim.sock`.
+- `-ginkgo.skip`: Skip the tests that match the regular expression.
+- `-parallel`: The number of parallel test nodes to run (default 1). ginkgo must be installed to run parallel tests.
+- `-h`: Show help and all supported options.
diff --git a/contributors/devel/e2e-tests.md b/contributors/devel/e2e-tests.md
index bd20ee4e..67453ba5 100644
--- a/contributors/devel/e2e-tests.md
+++ b/contributors/devel/e2e-tests.md
@@ -414,8 +414,14 @@ end of aforementioned script.
 
 #### Testing against local clusters
 
-In order to run an E2E test against a locally running cluster, point the tests
-at a custom host directly:
+In order to run an E2E test against a locally running cluster, first make sure
+to have a local build of the tests:
+
+```sh
+go run hack/e2e.go -- --build
+```
+
+Then point the tests at a custom host directly:
 
 ```sh
 export KUBECONFIG=/path/to/kubeconfig
@@ -430,6 +436,14 @@ To control the tests that are run:
 go run hack/e2e.go -- --provider=local --test --test_args="--ginkgo.focus=Secrets"
 ```
 
+You will also likely need to specify `minStartupPods` to match the number of
+nodes in your cluster. If you're testing against a cluster set up by
+`local-up-cluster.sh`, you will need to do the following:
+
+```sh
+go run hack/e2e.go -- --provider=local --test --test_args="--minStartupPods=1 --ginkgo.focus=Secrets"
+```
+
 ### Version-skewed and upgrade testing
 
 We run version-skewed tests to check that newer versions of Kubernetes work
diff --git a/contributors/devel/help-wanted.md b/contributors/devel/help-wanted.md
index eb1038a4..1d4594ec 100644
--- a/contributors/devel/help-wanted.md
+++ b/contributors/devel/help-wanted.md
@@ -1,13 +1,141 @@
-# Help Wanted
+# Overview
+
+We use two labels [help wanted](#help-wanted) and [good first
+issue](#good-first-issue) to identify issues that have been specially groomed
+for new contributors. The `good first issue` label is a subset of `help wanted`
+label, indicating that members have committed to providing extra assistance for
+new contributors. All `good first issue` items also have the `help wanted`
+label.
+
+We also have some [suggestions](#suggestions) for using these labels to help
+grow and improve our community.
+
+## Help Wanted
 
 Items marked with the `help wanted` label need to ensure that they are:
 
-- Sufficiently actionable: clear description of what should be done
-- Tractable for new/casual contributors: there is documentation how that type of change should be made
-- Goldilocks priority: Not too high that a core contributor should do it, but not too low that it isn't useful enough for a core contributor to spend time to review it, answer questions, help get it into a release, etc.
-- Up to date: Often these issues become obsolete and have already been done, are no longer desirable, no longer make sense, change in priority, change in difficulty, etc.
+- **Low Barrier to Entry**
+
+  It should be tractable for new contributors. Documentation on how that type of
+  change should be made should already exist.
+
+- **Clear Task**
+
+  The task is agreed upon and does not require further discussions in the
+  community. Call out if that area of code is untested and requires new
+  fixtures.
+
+  API / CLI behavior is decided and included in the OP issue, for example: _"The
+  new command syntax is `svcat unbind NAME [--orphan] [--timeout 5m]`"_, with
+  expected validations called out.
+
+- **Goldilocks priority**
+
+  Not too high that a core contributor should do it, but not too low that it
+  isn't useful enough for a core contributor to spend time to review it, answer
+  questions, help get it into a release, etc.
+
+- **Up-To-Date**
+
+  Often these issues become obsolete and have already been done, are no longer
+  desired, no longer make sense, have changed priority or difficulty , etc.
+
+Related commands:
+
+- `/help` : Adds the `help wanted` label to an issue.
+- `/remove-help` : Removes the `help wanted` label from an issue. If the
+  `good first issue` label is present, it is removed as well.
+
+## Good First Issue
+
+Items marked with the `good first issue` label are intended for _first-time
+contributors_. It indicates that members will keep an eye out for these pull
+requests and shepherd it through our processes.
+
+**New contributors should not be left to find an approver, ping for reviews,
+decipher prow commands, or identify that their build failed due to a flake.**
+This makes new contributors feel welcome, valued, and assures them that they
+will have an extra level of help with their first contribution.
+
+After a contributor has successfully completed 1-2 `good first issue`'s, they
+should be ready to move on to `help wanted` items, saving remaining `good first
+issue`'s for other new contributors.
+
+These items need to ensure that they follow the guidelines for `help wanted`
+labels (above) in addition to meeting the following criteria:
+
+- **No Barrier to Entry**
+
+  The task is something that a new contributor can tackle without advanced
+  setup, or domain knowledge.
+
+- **Solution Explained**
+
+  The recommended solution is clearly described in the issue.
+
+- **Provides Context**
+
+  If background knowledge is required, this should be explicitly mentioned and a
+  list of suggested readings included.
+
+- **Gives Examples**
+
+  Link to examples of similar implementations so new contributors have a
+  reference guide for their changes.
+
+- **Identifies Relevant Code**
+
+  The relevant code and tests to be changed should be linked in the issue.
+
+- **Ready to Test**
+
+  There should be existing tests that can be modified, or existing test cases
+  fit to be copied. If the area of code doesn't have tests, before labeling the
+  issue, add a test fixture. This prep often makes a great `help wanted` task!
 
 Related commands:
 
-- `/help` : adds the `help wanted` label to an issue
-- `/remove-help` : removes the `help wanted` label from an issue
\ No newline at end of file
+- `/good-first-issue` : Adds the `good first issue` label to an issue. Also adds
+  the `help wanted` label, if not already present.
+- `/remove-good-first-issue` : Removes the `good first issue` label from an
+  issue.
+
+# Suggestions
+
+We encourage our more experienced members to help new contributors, so that the
+Kubernetes community can continue to grow and maintain the kind, inclusive
+community that we all enjoy today.
+
+The following suggestions go a long way toward preventing "drive-by" PRs, and
+ensure that our investment in new contributors is rewarded by them coming back
+and becoming regulars.
+
+Provide extra assistance during reviews on `good first issue` pull requests:
+- Answer questions and identify useful docs.
+- Offer advice such as _"One way to reproduce this in a cluster is to do X and
+  then you can use kubectl to    poke around"_, or _"Did you know that you can
+  use fake clients to setup and test this easier?"_.
+- Help new contributors learn enough about the project, setting up their
+  environment, running tests, and navigating this area of the code so that they
+  can tackle a related `help wanted` issue next time.
+
+If you make someone feel like a part of our community, that it's safe to ask
+questions, that people will let them know the rules/norms, that their
+contributions are helpful and appreciated... they will stick around! 🌈
+- Encourage new contributors to seek help on the appropriate slack channels,
+  introduce them, and include them in your conversations.
+- Invite them to the SIG meetings.
+- Give credit to new contributors so that others get to know them, _"Hey, would
+  someone help give a second LGTM on @newperson's first PR on chocolate
+  bunnies?"_. Mention them in the SIG channel/meeting, thank them on twitter or
+  #shoutouts.
+- Use all the emoji in your approve or lgtm comment. 💖 🚀
+- Let them know that their `good first issue` is getting extra attention to make
+  the first one easier and help them find a follow-up issue.
+- Suggest a related `help wanted` so that can build up experience in an area.
+- People are more likely to continue contributing when they know what to expect,
+  what's the acceptable way to ask for people to review a PR, nudge things along
+  when a PR is stalled. Show them how we operate by helping move their first PR
+  along.
+- If you have time, let the contributor know that they can DM you with questions
+  that they aren't yet comfortable asking the wider group.
diff --git a/contributors/guide/README.md b/contributors/guide/README.md
index ad5cf2e1..d2540117 100644
--- a/contributors/guide/README.md
+++ b/contributors/guide/README.md
@@ -72,7 +72,9 @@ You get the idea - if you ever see something you think should be fixed, you shou
 ### Find a good first topic
 
 There are multiple repositories within the Kubernetes community and a full list of repositories can be found [here](https://github.com/kubernetes/).
-Each repository in the Kubernetes organization has beginner-friendly issues that provide a good first issue. For example, [kubernetes/kubernetes](https://git.k8s.io/kubernetes) has [help wanted issues](https://go.k8s.io/help-wanted) that should not need deep knowledge of the system.
+Each repository in the Kubernetes organization has beginner-friendly issues that provide a good first issue. For example, [kubernetes/kubernetes](https://git.k8s.io/kubernetes) has [help wanted](https://go.k8s.io/help-wanted) and [good first issue](https://github.com/kubernetes/kubernetes/labels/good%20first%20issue) labels for issues that should not need deep knowledge of the system.
+The `good first issue` label indicates that members have committed to providing extra assistance for new contributors.
+
 Another good strategy is to find a documentation improvement, such as a missing/broken link, which will give you exposure to the code submission/review process without the added complication of technical depth. Please see [Contributing](#contributing) below for the workflow.
 
 ### Learn about SIGs
diff --git a/contributors/guide/issue-triage.md b/contributors/guide/issue-triage.md
index 2ab43cc6..6230c7f0 100644
--- a/contributors/guide/issue-triage.md
+++ b/contributors/guide/issue-triage.md
@@ -33,7 +33,7 @@ for other github repositories related to Kubernetes is TBD.
 Most people can leave comments and open issues. They don't have the ability to
 set labels, change milestones and close other peoples issues. For that we use
 a bot to manage labelling and triaging. The bot has a set of
-[commands and permissions](https://git.k8s.io/test-infra/commands.md)
+[commands and permissions](https://go.k8s.io/bot-commands)
 and this document will cover the basic ones.
 
 ## Determine if it's a support request