move coding-conventions.md to guide
The coding-conventions document covers useful introductory guidance for all. This commit moves it out of the devel/ detail directory and into the contributor/guide, fixing up links from other doc's in this repo and leaving a cookie crumb of a document pointing at the new location. Signed-off-by: Tim Pepper <tpepper@vmware.com>
This commit is contained in:
Tim Pepper
parent
35d430cc0e
commit
b75e54d47e
|
|
@ -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))
|
||||
|
|
|
|||
|
|
@ -1,131 +1,3 @@
|
|||
# Coding Conventions
|
||||
This document has been moved to https://git.k8s.io/community/contributors/guide/coding-conventions.md
|
||||
|
||||
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
|
||||
This file is a placeholder to preserve links. Please remove after 3 months or the release of kubernetes 1.10, whichever comes first.
|
||||
|
|
|
|||
|
|
@ -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!**
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Please help write this section.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue