Add YAML and CRD conventions

This adds:
- light YAML schema conventions (camelCase keys)
- CRD conventions (adopting Kubernetes' own API conventions)

This change is borne out of the Airship SIG-YAML agreement that,
for Airship 2.0 work in particular, it makes sense to adhere to
Kubernetes' own conventions in these regards.

Change-Id: I86c7ccae25923242a1104189622e2421460cd350

doc/source/code-conventions.rst

@@ -158,6 +158,20 @@ Airship components must provide for automated checking of their formatting
 standards, such as the lint step noted above in the makefile. Components may
 provide automated reformatting.
 
+YAML Schema
+~~~~~~~~~~~
+YAML schema defined by Airship should have key names that follow camelCase
+naming conventions.
+
+Note that Airship also integrates and consumes a number of projects from
+other open source communities, which may have their own style conventions,
+and which will therefore be reflected in Airship deployment manifests.
+Those fall outside the scope of these Airship guidelines.
+
+Any YAML schema that violate this convention at the time of this writing
+(e.g. with snake_case keys) may be either grandfathered in, or converted,
+at the development team's discretion.
+
 Tests Location
 ~~~~~~~~~~~~~~
 Tests should be in parallel structures to the related code, unless dictated by

doc/source/conventions.rst

@@ -40,6 +40,7 @@ Conventions and Standards
 
    api-conventions
    code-conventions
+   crd-conventions
    documentation-conventions
    service-logging-conventions
 

doc/source/crd-conventions.rst

@@ -0,0 +1,44 @@
+..
+      Copyright 2019 AT&T Intellectual Property.
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _crd-conventions:
+
+CRD Conventions
+===============
+
+Airship will use CRDs to enrich the Kubernetes API with Airship-specific
+document schema.  Airship projects will follow the following conventions
+when defining Custom Resource Definitions (CRDs).
+
+Note that Airship integrates and consumes a number of projects from
+other open source communities, which may have their own style conventions,
+and which will therefore be reflected in Airship deployment manifests.
+Those fall outside the scope of these Airship guidelines.
+
+In general, Airship will follow the
+`Kubernetes API Conventions`_ when defining CRDs.  These cover naming
+conventions (such as using camelCase for key names),
+expected document structure, HTTP request verbs and status codes,
+and behavioral norms.
+
+Exceptions or restrictions from the Kubernetes conventions are specified below;
+this list may grow in the future.
+
+*  The ``apiGroup`` (and ``apiVersion``) for Airship CRDs will have values
+   following the convention ``<function>.airshipit.org``.
+
+.. _Kubernetes API Conventions: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
+