feat(docs): add deprecation documentation (spinnaker#1744)

* feat(docs): improve discoverability of contributor docs

* feat(docs): add field deprecation docs

* feat(docs): document how to add minimum Spinnaker version to new fields

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

CONTRIBUTING.md

@@ -64,3 +64,13 @@ make
 > WARNING! Since this project uses one gradle project for two executables, you
 > currently can't run `make` and `./gradlew` at the same time (one of the two
 > will likely hang indefinitely).
+
+## Adding Functionality
+
+* [Adding a config parameter](/docs/adding-a-config-parameter.md)
+* [Adding a provider](/docs/adding-a-provider.md)
+
+## Deprecating Functionality
+
+* [Deprecating a command](/docs/deprecating-commands.md)
+* [Deprecating a field](/docs/deprecating-fields.md)

docs/adding-a-config-parameter.md

@@ -34,6 +34,11 @@ In our example PR, we add the `List<String> omitNamespaces` field to the
 `KubernetesAccount` class as shown
 [here](https://github.com/spinnaker/halyard/pull/498/files#diff-f14f7138f2eb7e043ee1ff1bd8bc7a0bR46).
 
+If the field requires a minimum Spinnaker version, annotate it with
+`ValidForSpinnakerVersion`, indicating the first Spinnaker version in which the
+field is supported as the `lowerBound`. Optionally, supply a message indicating
+why the field is unsupported in earlier versions as the `tooLowMessage`.
+
 ## 2. Update the config generation
 
 The structure of the halconfig should closely mirror that of whatever

docs/deprecating-fields.md

@@ -0,0 +1,13 @@
+# Deprecating Fields
+
+When a field is no longer read by any Spinnaker microservice, the field should
+be deprecated in Halyard so users know it is safe to remove from their
+halconfig.
+
+To deprecate a field, annotate it with `ValidForSpinnakerVersion`, indicating
+the first Spinnaker version in which the field is no longer necessary as the
+`upperBound`. Optionally, supply a message indicating why the field is no
+longer required as the `tooHighMessage`.
+
+See the `artifacts` and `artifactsRewrite` fields in the `Features` class as
+examples of deprecated fields.