You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/devel/api-conventions.md
+7
Original file line number
Diff line number
Diff line change
@@ -713,6 +713,13 @@ Annotations have very different intended usage from labels. We expect them to be
713
713
714
714
In fact, experimental API fields, including to represent fields of newer alpha/beta API versions in the older, stable storage version, may be represented as annotations with the prefix `experimental.kubernetes.io/`.
715
715
716
+
Other advice regarding use of labels, annotations, and other generic map keys by Kubernetes components and tools:
717
+
- Key names should be all lowercase, with words separated by dashes, such as `desired-replicas`
718
+
- Prefix the key with `kubernetes.io/` or `foo.kubernetes.io/`, preferably the latter if the label/annotation is specific to `foo`
719
+
- For instance, prefer `service-account.kubernetes.io/name` over `kubernetes.io/service-account.name`
720
+
- Use annotations to store API extensions that the controller responsible for the resource doesn't need to know about, experimental fields that aren't intended to be generally used API fields, etc. Beware that annotations aren't automatically handled by the API conversion machinery.
- If reviewers ask questions about why the code is the way it is, that's a sign that comments might be helpful.
44
+
- Command-line flags should use dashes, not underscores
45
+
- Naming
46
+
- Please consider package name when selecting an interface name, and avoid redundancy.
47
+
- e.g.: `storage.Interface` is better than `storage.StorageInterface`.
48
+
- Do not use uppercase characters, underscores, or dashes in package names.
49
+
- Please consider parent directory name when choosing a package name.
50
+
- so pkg/controllers/autoscaler/foo.go should say `package autoscaler` not `package autoscalercontroller`.
51
+
- Unless there's a good reason, the `package foo` line should match the name of the directory in which the .go file exists.
52
+
- Importers can use a different name if they need to disambiguate.
53
+
- API conventions
54
+
-[API changes](api_changes.md)
55
+
-[API conventions](api-conventions.md)
56
+
-[Kubectl conventions](kubectl-conventions.md)
57
+
-[Logging conventions](logging.md)
58
+
59
+
Testing conventions
60
+
- All new packages and most new significant functionality must come with unit tests
61
+
- Table-driven tests are preferred for testing multiple scenarios/inputs; for example, see [TestNamespaceAuthorization](../../test/integration/auth_test.go)
62
+
- Significant features should come with integration (test/integration) and/or end-to-end (test/e2e) tests
63
+
- Including new kubectl commands and major features of existing commands
64
+
- 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).
65
+
66
+
Directory and file conventions
67
+
- Avoid package sprawl. Find an appropriate subdirectory for new packages. (See [#4851](http://issues.k8s.io/4851) for discussion.)
68
+
- Libraries with no more appropriate home belong in new package subdirectories of pkg/util
69
+
- 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
70
+
- Go source files and directories use underscores, not dashes
71
+
- Package directories should generally avoid using separators as much as possible (when packages are multiple words, they usually should be in nested subdirectories).
72
+
- Document directories and filenames should use dashes rather than underscores
73
+
- 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.
74
+
- Examples should also illustrate [best practices for using the system](../user-guide/config-best-practices.md)
75
+
- Third-party code
76
+
- Third-party Go code is managed using Godeps
77
+
- Other third-party code belongs in /third_party
78
+
- Third-party code must include licenses
79
+
- This includes modified third-party code and excerpts, as well
Copy file name to clipboardexpand all lines: docs/devel/development.md
+2
Original file line number
Diff line number
Diff line change
@@ -112,6 +112,8 @@ fixups (e.g. automated doc formatting), use one or more commits for the
112
112
changes to tooling and a final commit to apply the fixup en masse. This makes
113
113
reviews much easier.
114
114
115
+
See [Faster Reviews](faster_reviews.md) for more details.
116
+
115
117
## godep and dependency management
116
118
117
119
Kubernetes uses [godep](https://github.com/tools/godep) to manage dependencies. It is not strictly required for building Kubernetes but it is required when managing dependencies under the Godeps/ tree, and is required by a number of the build and test scripts. Please make sure that ``godep`` is installed and in your ``$PATH``.
Copy file name to clipboardexpand all lines: docs/devel/faster_reviews.md
+27-5
Original file line number
Diff line number
Diff line change
@@ -53,15 +53,24 @@ later, just as soon as they have more free time (ha!).
53
53
54
54
Let's talk about how to avoid this.
55
55
56
+
## 0. Familiarize yourself with project conventions
57
+
58
+
*[Development guide](development.md)
59
+
*[Coding conventions](coding-conventions.md)
60
+
*[API conventions](api-conventions.md)
61
+
*[Kubectl conventions](kubectl-conventions.md)
62
+
56
63
## 1. Don't build a cathedral in one PR
57
64
58
65
Are you sure FeatureX is something the Kubernetes team wants or will accept, or
59
66
that it is implemented to fit with other changes in flight? Are you willing to
60
67
bet a few days or weeks of work on it? If you have any doubt at all about the
61
-
usefulness of your feature or the design - make a proposal doc or a sketch PR
62
-
or both. Write or code up just enough to express the idea and the design and
63
-
why you made those choices, then get feedback on this. Now, when we ask you to
64
-
change a bunch of facets of the design, you don't have to re-write it all.
68
+
usefulness of your feature or the design - make a proposal doc (in docs/proposals;
69
+
for example [the QoS proposal](http://prs.k8s.io/11713)) or a sketch PR (e.g., just
70
+
the API or Go interface) or both. Write or code up just enough to express the idea
71
+
and the design and why you made those choices, then get feedback on this. Be clear
72
+
about what type of feedback you are asking for. Now, if we ask you to change a
73
+
bunch of facets of the design, you won't have to re-write it all.
65
74
66
75
## 2. Smaller diffs are exponentially better
67
76
@@ -154,7 +163,20 @@ commit and re-push. Your reviewer can then look at that commit on its own - so
154
163
much faster to review than starting over.
155
164
156
165
We might still ask you to clean up your commits at the very end, for the sake
157
-
of a more readable history.
166
+
of a more readable history, but don't do this until asked, typically at the point
167
+
where the PR would otherwise be tagged LGTM.
168
+
169
+
General squashing guidelines:
170
+
171
+
* Sausage => squash
172
+
173
+
When there are several commits to fix bugs in the original commit(s), address reviewer feedback, etc. Really we only want to see the end state and commit message for the whole PR.
174
+
175
+
* Layers => don't squash
176
+
177
+
When there are independent changes layered upon each other to achieve a single goal. For instance, writing a code munger could be one commit, applying it could be another, and adding a precommit check could be a third. One could argue they should be separate PRs, but there's really no way to test/review the munger without seeing it applied, and there needs to be a precommit check to ensure the munged output doesn't immediately get out of date.
178
+
179
+
A commit, as much as possible, should be a single logical change. Each commit should always have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended. Do not link pull requests by `#` in a commit description, because GitHub creates lots of spam. Instead, reference other PRs via the PR your commit is in.
Copy file name to clipboardexpand all lines: docs/devel/kubectl-conventions.md
+26-1
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ Documentation for other releases can be found at
34
34
Kubectl Conventions
35
35
===================
36
36
37
-
Updated: 8/12/2015
37
+
Updated: 8/27/2015
38
38
39
39
**Table of Contents**
40
40
<!-- BEGIN MUNGE: GENERATED_TOC -->
@@ -77,6 +77,31 @@ Updated: 8/12/2015
77
77
* Flags are all lowercase, with words separated by hyphens
78
78
* Flag names and single-character aliases should have the same meaning across all commands
79
79
* Command-line flags corresponding to API fields should accept API enums exactly (e.g., --restart=Always)
80
+
* Do not reuse flags for different semantic purposes, and do not use different flag names for the same semantic purpose -- grep for `"Flags()"` before adding a new flag
81
+
* Use short flags sparingly, only for the most frequently used options, prefer lowercase over uppercase for the most common cases, try to stick to well known conventions for UNIX commands and/or Docker, where they exist, and update this list when adding new short flags
82
+
*`-f`: Resource file
83
+
* also used for `--follow` in `logs`, but should be deprecated in favor of `-F`
84
+
*`-l`: Label selector
85
+
* also used for `--labels` in `expose`, but should be deprecated
86
+
*`-L`: Label columns
87
+
*`-c`: Container
88
+
* also used for `--client` in `version`, but should be deprecated
89
+
*`-i`: Attach stdin
90
+
*`-t`: Allocate TTY
91
+
* also used for `--template`, but deprecated
92
+
*`-w`: Watch (currently also used for `--www` in `proxy`, but should be deprecated)
93
+
*`-p`: Previous
94
+
* also used for `--pod` in `exec`, but deprecated
95
+
* also used for `--patch` in `patch`, but should be deprecated
96
+
* also used for `--port` in `proxy`, but should be deprecated
97
+
*`-P`: Static file prefix in `proxy`, but should be deprecated
98
+
*`-r`: Replicas
99
+
*`-u`: Unix socket
100
+
*`-v`: Verbose logging level
101
+
*`--dry-run`: Don't modify the live state; simulate the mutation and display the output
102
+
*`--local`: Don't contact the server; just do local read, transformation, generation, etc. and display the output
103
+
*`--output-version=...`: Convert the output to a different API group/version
0 commit comments