Convert decision documents to ADR format

- Convert decision documents to ADR format

Related #259



Signed-off-by: Robert Marshall <rmarshall@gitlab.com>

doc/architecture/README.md

@@ -4,7 +4,9 @@
 
 - [Architectural Vision](vision.md)
 
-## Decisions
-- [Product Name](decisions/product_name.md)
-- [User Experience Targets: Alpha Release](decisions/alpha_experience.md)
+## Architectural Decision Records
 
+- [0001: Product Name is Orchestrator](decisions/0001_product_name_is_orchestrator.md)
+- [0002: User Experience Targets: Alpha Release](decisions/0002_user_experience_targets_alpha_release.md)
+- [0003. Architectural Decision Record Format](decisions/0003_architectural_decision_format.md)
+- [0004. Methods for Handling Secrets](decisions/0004_methods_for_handling_secrets.md)

doc/architecture/decisions/product_name.md → doc/architecture/decisions/0001_product_name_is_orchestrator.md

-# Product Name is Orchestrator
+# 0001. Product Name is Orchestrator
+
+- Proposed: 2019-09-19
+- Accepted: 2020-07-10
+
+## Status
+
+Accepted
+
+## Context
 
 [Review the original discussion issue for full context](https://gitlab.com/gitlab-org/gitlab-orchestrator/-/issues/159)
 
@@ -6,3 +15,12 @@
 1. The few alternate suggestions made did not garner upvotes/traction beyond simply being an alternative
 1. Difficulty coming up with alternate names conveying the tool's purpose demonstrates that **Orchestrator** is likely the [most boring solution](https://about.gitlab.com/handbook/values/#boring-solutions)
 1. If the name becomes a serious problem, we can [follow the two way door principle](https://about.gitlab.com/handbook/values/#make-two-way-door-decisions)
+
+## Decision
+
+Orchestrator shall be retained as the project name.
+
+## Consequences
+
+1. Orchestrator may be confused with other tools that do more generic
+   orchestration tasks.

doc/architecture/decisions/alpha_experience.md → doc/architecture/decisions/0002_user_experience_targets_alpha_release.md

-# User Experience Targets: Alpha Release
+# 0002. User Experience Targets: Alpha Release
+
+- Proposed: 2020-02-28
+- Accepted: 2020-07-08
+
+## Status
+
+Accepted
+
+## Context
 
 [Review the original discussion issue for full context](https://gitlab.com/gitlab-org/gitlab-orchestrator/-/issues/31)
 
+## Decision
+
 1. Command line interface to be written in **Go** per #29
     - Follow the pattern established by other communities and tools with widespread adoption.
     - GitLab has more maintainers to support **Go** than the alternatives.
@@ -18,3 +29,15 @@
     - The minimum viable product our customers ask for is a command line interface. We can easily add a graphical interface later.
 1. [Secrets management will be handled via its own discussion due to the topic's complexity](https://gitlab.com/gitlab-org/gitlab-orchestrator/-/issues/205).
     - The command line interface design can proceed on other topics until secrets management is firm.
+
+## Consequences
+
+- Benefits
+    1. Input validation and testing improves immensely.
+    1. Templates and data bindings become less onerous to maintain.
+    1. Structured configuration files become easier to maintain.
+- Drawbacks
+    1. Converting to **Go** requires a full refactor of tooling. Mitigated
+       by being projected to happen just once during the project lifecycle.
+    1. Go is not as accessible to some users. Mitigate by improving logging
+       facilities in the tooling.

doc/architecture/decisions/0003_architectural_decision_record_format.md

+# 0003. Architectural Decision Record Format
+
+- Proposed: 2020-07-28
+- Accepted: 2020-07-29
+
+## Status
+
+Accepted
+
+## Context
+
+[Review the original discussion issue for full context](https://gitlab.com/gitlab-org/gitlab-orchestrator/-/issues/259)
+
+1. Need to track decisions including when our [two-way door policy](https://about.gitlab.com/handbook/values/#make-two-way-door-decisions) is used to make changes.
+1. Structured format will make it easier to follow the decision tree.
+
+## Decision
+
+1. Manual format in markdown where this example is in `/doc/architecture/decisions/0001_my_decision_record.md`
+    ```markdown
+    # 0001. My Decision Record
+
+    Proposed: YYYY-MM-DD
+    Accepted|Rejected: YYYY-MM-DD
+    Deprecated|Superceded: YYYY-MM-DD
+
+    ## Status
+
+    Accepted|Proposed|Rejected|Deprecated|Superceded
+
+    ## Context
+
+    Link to initial issue to discuss
+
+    Prose describing contexts and constraints that impacted the decision making process.
+
+    ## Decision
+
+    Document the outcome of the change proposal.
+
+    ## Consequences
+
+    List tradeoffs made in this decision.
+    ```
+1. Track superseded items manually in `/doc/architecture/decisions/metadata.json`
+    ```json
+    {
+        "superseded": {
+            new_decision: old_decision
+        }
+    }
+    ```
+
+## Consequences
+
+1. Start documenting in a more structured way immediately.
+1. Lack of tooling means we have a potential for typos or errors. [Mitigate this with tooling updates](https://gitlab.com/gitlab-org/gitlab-orchestrator/-/issues/265)

doc/architecture/decisions/methods_for_handling_secrets.md → doc/architecture/decisions/0004_methods_for_handling_secrets.md

 # Methods for Handling Secrets
 
 - Proposed: 2020-07-29
+- Accepted: 2020-07-31
 
 ## Status
 
-Proposed
+Accepted
 
 ## Context
 

doc/architecture/decisions/metadata.json

+{
+    "superseded": {
+    }
+}