Merge pull request #1676 from tpepper/guide_moves

Guide moves

8 files changed, 142 insertions, 170 deletions

diff --git a/contributors/devel/README.md b/contributors/devel/README.md
index 2c416296..7e93e6df 100644
--- a/contributors/devel/README.md
+++ b/contributors/devel/README.md
@@ -37,7 +37,7 @@ Guide](http://kubernetes.io/docs/admin/).
   ([instrumentation.md](instrumentation.md)): How to add a new metrics to the
   Kubernetes code base.
 
-* **Coding Conventions** ([coding-conventions.md](coding-conventions.md)):
+* **Coding Conventions** ([coding-conventions.md](../guide/coding-conventions.md)):
   Coding style advice for contributors.
 
 * **Document Conventions** ([how-to-doc.md](how-to-doc.md))
diff --git a/contributors/devel/coding-conventions.md b/contributors/devel/coding-conventions.md
index 17c890a9..23775c55 100644
--- a/contributors/devel/coding-conventions.md
+++ b/contributors/devel/coding-conventions.md
@@ -1,138 +1,3 @@
-# Coding Conventions
+This document has been moved to https://git.k8s.io/community/contributors/guide/coding-conventions.md
 
-Updated: 5/3/2016
-
-**Table of Contents**
-
-- [Coding Conventions](#coding-conventions)
-  - [Code conventions](#code-conventions)
-  - [Testing conventions](#testing-conventions)
-  - [Directory and file conventions](#directory-and-file-conventions)
-  - [Coding advice](#coding-advice)
-
-
-## Code conventions
-
-  - Bash
-
-    - https://google.github.io/styleguide/shell.xml
-
-    - Ensure that build, release, test, and cluster-management scripts run on
-OS X
-
-  - Go
-
-    - [Go Code Review
-Comments](https://github.com/golang/go/wiki/CodeReviewComments)
-
-    - [Effective Go](https://golang.org/doc/effective_go.html)
-
-    - Comment your code.
-      - [Go's commenting
-conventions](http://blog.golang.org/godoc-documenting-go-code)
-      - If reviewers ask questions about why the code is the way it is, that's a
-sign that comments might be helpful.
-
-
-    - Command-line flags should use dashes, not underscores
-
-
-    - Naming
-      - Please consider package name when selecting an interface name, and avoid
-redundancy.
-
-          - e.g.: `storage.Interface` is better than `storage.StorageInterface`.
-
-      - Do not use uppercase characters, underscores, or dashes in package
-names.
-      - Please consider parent directory name when choosing a package name.
-
-          - so pkg/controllers/autoscaler/foo.go should say `package autoscaler`
-not `package autoscalercontroller`.
-          - Unless there's a good reason, the `package foo` line should match
-the name of the directory in which the .go file exists.
-          - Importers can use a different name if they need to disambiguate.
-
-      - Locks should be called `lock` and should never be embedded (always `lock
-sync.Mutex`). When multiple locks are present, give each lock a distinct name
-following Go conventions - `stateLock`, `mapLock` etc.
-
-    - [API changes](api_changes.md)
-
-    - [API conventions](api-conventions.md)
-
-    - [Kubectl conventions](kubectl-conventions.md)
-
-    - [Logging conventions](logging.md)
-
-## Testing conventions
-
-  - All new packages and most new significant functionality must come with unit
-tests
-
-  - Table-driven tests are preferred for testing multiple scenarios/inputs; for
-example, see [TestNamespaceAuthorization](https://git.k8s.io/kubernetes/test/integration/auth/auth_test.go)
-
-  - Significant features should come with integration (test/integration) and/or
-[end-to-end (test/e2e) tests](e2e-tests.md)
-    - Including new kubectl commands and major features of existing commands
-
-  - Unit tests must pass on OS X and Windows platforms - if you use Linux
-specific features, your test case must either be skipped on windows or compiled
-out (skipped is better when running Linux specific commands, compiled out is
-required when your code does not compile on Windows).
-
-  - Avoid relying on Docker hub (e.g. pull from Docker hub). Use gcr.io instead.
-
-  - Avoid waiting for a short amount of time (or without waiting) and expect an
-asynchronous thing to happen (e.g. wait for 1 seconds and expect a Pod to be
-running). Wait and retry instead.
-
-  - See the [testing guide](testing.md) for additional testing advice.
-
-## Directory and file conventions
-
-  - Avoid package sprawl. Find an appropriate subdirectory for new packages.
-(See [#4851](http://issues.k8s.io/4851) for discussion.)
-    - Libraries with no more appropriate home belong in new package
-subdirectories of pkg/util
-
-  - Avoid general utility packages. Packages called "util" are suspect. Instead,
-derive a name that describes your desired function. For example, the utility
-functions dealing with waiting for operations are in the "wait" package and
-include functionality like Poll. So the full name is wait.Poll
-
-  - All filenames should be lowercase
-
-  - Go source files and directories use underscores, not dashes
-    - Package directories should generally avoid using separators as much as
-possible (when packages are multiple words, they usually should be in nested
-subdirectories).
-
-  - Document directories and filenames should use dashes rather than underscores
-
-  - Contrived examples that illustrate system features belong in
-/docs/user-guide or /docs/admin, depending on whether it is a feature primarily
-intended for users that deploy applications or cluster administrators,
-respectively. Actual application examples belong in /examples.
-    - Examples should also illustrate [best practices for configuration and
-using the system](https://kubernetes.io/docs/user-guide/config-best-practices/)
-
-  - Third-party code
-
-    - Go code for normal third-party dependencies is managed using
-[Godeps](https://github.com/tools/godep)
-
-    - Other third-party code belongs in `/third_party`
-      - forked third party Go code goes in `/third_party/forked`
-      - forked _golang stdlib_ code goes in `/third_party/golang`
-
-    - Third-party code must include licenses
-
-    - This includes modified third-party code and excerpts, as well
-
-## Coding advice
-
-  - Go
-
-    - [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f)
+This file is a placeholder to preserve links.  Please remove after 3 months or the release of kubernetes 1.10, whichever comes first.
diff --git a/contributors/devel/e2e-tests.md b/contributors/devel/e2e-tests.md
index cf4127d0..544b546a 100644
--- a/contributors/devel/e2e-tests.md
+++ b/contributors/devel/e2e-tests.md
@@ -595,7 +595,7 @@ any other labels.
 As each new release of Kubernetes providers new functionality, the subset of
 tests necessary to demonstrate conformance grows with each release. Conformance
 is thus considered versioned, with the same backwards compatibility guarantees
-as laid out in [our versioning policy](../design/versioning.md#supported-releases).
+as laid out in [our versioning policy](../design-proposals/versioning.md#supported-releases).
 Conformance tests for a given version should be run off of the release branch
 that corresponds to that version. Thus `v1.2` conformance tests would be run
 from the head of the `release-1.2` branch. eg:
@@ -798,6 +798,6 @@ metrics that kubernetes provides.
 
 ## One More Thing
 
-You should also know the [testing conventions](coding-conventions.md#testing-conventions).
+You should also know the [testing conventions](../guide/coding-conventions.md#testing-conventions).
 
 **HAPPY TESTING!**
diff --git a/contributors/devel/go-code.md b/contributors/devel/go-code.md
index 80ffa9d5..4454e400 100644
--- a/contributors/devel/go-code.md
+++ b/contributors/devel/go-code.md
@@ -1,28 +1,3 @@
-# Kubernetes Go Tools and Tips
-
-Kubernetes is one of the largest open source Go projects. Good tooling and a solid understanding of
-Go is critical to Kubernetes development. This document provides a collection of resources, tools,
-and tips that our developers have found useful.
-
-## Recommended Reading
-
-- [Kubernetes Go development environment](development.md#go-development-environment)
-- [The Go Spec](https://golang.org/ref/spec) - The Go Programming Language
-  Specification.
-- [Go Tour](https://tour.golang.org/welcome/2) - Official Go tutorial.
-- [Effective Go](https://golang.org/doc/effective_go.html) - A good collection of Go advice.
-- [Kubernetes Code conventions](coding-conventions.md) - Style guide for Kubernetes code.
-- [Three Go Landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f) - Surprising behavior in the Go language. These have caused real bugs!
-
-## Recommended Tools
-
-- [godep](https://github.com/tools/godep) - Used for Kubernetes dependency management. See also [Kubernetes godep and dependency management](development.md#godep-and-dependency-management).
-- [Go Version Manager](https://github.com/moovweb/gvm) - A handy tool for managing Go versions.
-- [godepq](https://github.com/google/godepq) - A tool for analyzing go import trees.
-
-## Go Tips
-
-- [Godoc bookmarklet](https://gist.github.com/timstclair/c891fb8aeb24d663026371d91dcdb3fc) - Navigate from a github page to the corresponding godoc page.
-- Consider making a separate Go tree for each project, which can make overlapping dependency management much easier. Remember to set the `$GOPATH` correctly! Consider [scripting](https://gist.github.com/timstclair/17ca792a20e0d83b06dddef7d77b1ea0) this.
-- Emacs users - setup [go-mode](https://github.com/dominikh/go-mode.el).
+This document's content has been rolled into https://git.k8s.io/community/contributors/guide/coding-conventions.md
 
+This file is a placeholder to preserve links.  Please remove after 3 months or the release of kubernetes 1.10, whichever comes first.
diff --git a/contributors/devel/pull-requests.md b/contributors/devel/pull-requests.md
index 50e457a2..1fb42141 100644
--- a/contributors/devel/pull-requests.md
+++ b/contributors/devel/pull-requests.md
@@ -210,7 +210,7 @@ Let's talk about best practices so your PR gets reviewed quickly.
 ## 0. Familiarize yourself with project conventions
 
 * [Development guide](development.md)
-* [Coding conventions](coding-conventions.md)
+* [Coding conventions](../guide/coding-conventions.md)
 * [API conventions](api-conventions.md)
 * [Kubectl conventions](kubectl-conventions.md)
 
diff --git a/contributors/devel/testing.md b/contributors/devel/testing.md
index 340132d8..cd7dd124 100644
--- a/contributors/devel/testing.md
+++ b/contributors/devel/testing.md
@@ -41,7 +41,7 @@ passing, so it is often a good idea to make sure the e2e tests work as well.
   - Tests using linux-specific features must be skipped or compiled out.
   - Skipped is better, compiled out is required when it won't compile.
 * Concurrent unit test runs must pass.
-* See [coding conventions](coding-conventions.md).
+* See [coding conventions](../guide/coding-conventions.md).
 
 ### Run all unit tests
 
diff --git a/contributors/guide/README.md b/contributors/guide/README.md
index 279c38bd..897bef63 100644
--- a/contributors/guide/README.md
+++ b/contributors/guide/README.md
@@ -156,6 +156,7 @@ For a brief description of the importance of code review, please read [On Code R
 
 To make it easier for your PR to receive reviews, consider the reviewers will need you to:
 
+* follow the project [coding conventions](coding-conventions.md)
 * write [good commit messages](https://chris.beams.io/posts/git-commit/)
 * break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue
 * label PRs with appropriate SIGs and reviewers: to do this read the messages the bot sends you to guide you through the PR process
@@ -213,4 +214,4 @@ Kubernetes is the main focus of CloudNativeCon/KubeCon, held twice per year in E
 
 ## Mentorship
 
-* Please help write this section.
\ No newline at end of file
+* Please help write this section.
diff --git a/contributors/guide/coding-conventions.md b/contributors/guide/coding-conventions.md
new file mode 100644
index 00000000..644228b1
--- /dev/null
+++ b/contributors/guide/coding-conventions.md
@@ -0,0 +1,131 @@
+# Coding Conventions
+
+Updated: 1/24/2018
+
+**Table of Contents**
+
+- [Coding Conventions](#coding-conventions)
+  - [Code conventions](#code-conventions)
+  - [Testing conventions](#testing-conventions)
+  - [Directory and file conventions](#directory-and-file-conventions)
+
+## Code conventions
+
+  - Bash
+
+    - https://google.github.io/styleguide/shell.xml
+
+    - Ensure that build, release, test, and cluster-management scripts run on
+OS X
+
+  - Go
+
+    - [Go Code Review
+Comments](https://github.com/golang/go/wiki/CodeReviewComments)
+
+    - [Effective Go](https://golang.org/doc/effective_go.html)
+
+    - Know and avoid [Go landmines](https://gist.github.com/lavalamp/4bd23295a9f32706a48f)
+
+    - Comment your code.
+      - [Go's commenting
+conventions](http://blog.golang.org/godoc-documenting-go-code)
+      - If reviewers ask questions about why the code is the way it is, that's a
+sign that comments might be helpful.
+
+    - Command-line flags should use dashes, not underscores
+
+    - Naming
+      - Please consider package name when selecting an interface name, and avoid
+redundancy.
+
+          - e.g.: `storage.Interface` is better than `storage.StorageInterface`.
+
+      - Do not use uppercase characters, underscores, or dashes in package
+names.
+      - Please consider parent directory name when choosing a package name.
+
+          - so pkg/controllers/autoscaler/foo.go should say `package autoscaler`
+not `package autoscalercontroller`.
+          - Unless there's a good reason, the `package foo` line should match
+the name of the directory in which the .go file exists.
+          - Importers can use a different name if they need to disambiguate.
+
+      - Locks should be called `lock` and should never be embedded (always `lock
+sync.Mutex`). When multiple locks are present, give each lock a distinct name
+following Go conventions - `stateLock`, `mapLock` etc.
+
+    - [API changes](api_changes.md)
+
+    - [API conventions](api-conventions.md)
+
+    - [Kubectl conventions](kubectl-conventions.md)
+
+    - [Logging conventions](logging.md)
+
+## Testing conventions
+
+  - All new packages and most new significant functionality must come with unit
+tests
+
+  - Table-driven tests are preferred for testing multiple scenarios/inputs; for
+example, see [TestNamespaceAuthorization](https://git.k8s.io/kubernetes/test/integration/auth/auth_test.go)
+
+  - Significant features should come with integration (test/integration) and/or
+[end-to-end (test/e2e) tests](e2e-tests.md)
+    - Including new kubectl commands and major features of existing commands
+
+  - Unit tests must pass on OS X and Windows platforms - if you use Linux
+specific features, your test case must either be skipped on windows or compiled
+out (skipped is better when running Linux specific commands, compiled out is
+required when your code does not compile on Windows).
+
+  - Avoid relying on Docker hub (e.g. pull from Docker hub). Use gcr.io instead.
+
+  - Avoid waiting for a short amount of time (or without waiting) and expect an
+asynchronous thing to happen (e.g. wait for 1 seconds and expect a Pod to be
+running). Wait and retry instead.
+
+  - See the [testing guide](testing.md) for additional testing advice.
+
+## Directory and file conventions
+
+  - Avoid package sprawl. Find an appropriate subdirectory for new packages.
+(See [#4851](http://issues.k8s.io/4851) for discussion.)
+    - Libraries with no more appropriate home belong in new package
+subdirectories of pkg/util
+
+  - Avoid general utility packages. Packages called "util" are suspect. Instead,
+derive a name that describes your desired function. For example, the utility
+functions dealing with waiting for operations are in the "wait" package and
+include functionality like Poll. So the full name is wait.Poll
+
+  - All filenames should be lowercase
+
+  - Go source files and directories use underscores, not dashes
+    - Package directories should generally avoid using separators as much as
+possible (when packages are multiple words, they usually should be in nested
+subdirectories).
+
+  - Document directories and filenames should use dashes rather than underscores
+
+  - Contrived examples that illustrate system features belong in
+/docs/user-guide or /docs/admin, depending on whether it is a feature primarily
+intended for users that deploy applications or cluster administrators,
+respectively. Actual application examples belong in /examples.
+    - Examples should also illustrate [best practices for configuration and
+using the system](https://kubernetes.io/docs/user-guide/config-best-practices/)
+
+  - Third-party code
+
+    - Go code for normal third-party dependencies is managed using
+[Godeps](https://github.com/tools/godep) and is described in the kubernetes
+[godep guide](godep.md)
+
+    - Other third-party code belongs in `/third_party`
+      - forked third party Go code goes in `/third_party/forked`
+      - forked _golang stdlib_ code goes in `/third_party/forked/golang`
+
+    - Third-party code must include licenses
+
+    - This includes modified third-party code and excerpts, as well