Add naming conventions for images, repos, etc
@@ -44,7 +44,10 @@ components that make up the project, but exceptions are allowed when necessary.
## Motivation
The conventions are intended to help with consistency across the project. Users
-of the platform expect this consistency in the experience and operation of the cluster.
+of the platform expect consistency in the experience and operation of the cluster.
+Developers of the platform expect consistency in the code to quickly identify issuses
+across codebases. Consistency enables shared understanding, simplifies explanations,
+and reduces accidental complexity.
### Terminology, Grammar, and Spelling
@@ -61,12 +64,17 @@ We prefer clear and consistent names that describe the concepts in a human frien
For instance, the core component that rolls out the desired version of an OpenShift cluster is called the cluster-version-operator - it is an "operator" (a term with appropriate context in this domain) that controls the "version" of the "cluster". Other components reuse this pattern - this consistency allows a human to infer similarity and reorient as new or unfamiliar components are introduced over time. Likewise the API object that drives the behavior of the cluster related to versions and upgrades is known as `ClusterVersion` (allowing a human to guess at its function from either direction).
-* Image
- * Operator:
- * Non-operator:
-* GitHub Repository
- * Operator:
- * Non-operator:
+Once you have decided on a name for a new component, follow these conventions:
+
+* Image - images are tagged into ImageStreams to build OpenShift releases, they should be tagged with the component name
+ * Operator: [console-operator](https://github.com/openshift/release/blob/0c3425af83f0c4ba0080d3ee2746455396b4bc40/ci-operator/config/openshift/console-operator/openshift-console-operator-master.yaml#L22)
+ * Non-operator: [console](https://github.com/openshift/release/blob/0c3425af83f0c4ba0080d3ee2746455396b4bc40/ci-operator/config/openshift/console/openshift-console-master.yaml#L20)
+* GitHub repository - repositories should be easily identifiable and match the component name whenever possible. This allows others to find the code for your component among the hundreds of repositories that make up the OpenShift project.
+ * Operator: [openshift/console-operator](https://github.com/openshift/console-operator)
+ * Non-operator: [openshift/console](https://github.com/openshift/console-operator)
+* Git branches: branch maintenance is automated in OpenShift, breaking from convention will make it harder to support your repository
+ * `master` is used for active development
+ * `release-4.#` for maintenance branches, e.g. `release-4.5`
* API: follow the Kubernetes API [naming conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#naming-conventions)
#### Terms
