Update Contributor Guide & Add ADR docs (#356)

.adr-dir

@@ -0,0 +1 @@
+docs/adr

.tool-versions

@@ -1,2 +1,3 @@
 golang 1.16.7
 terraform 1.1.4
+adr-tools 3.0.0

CONTRIBUTING.md

@@ -21,10 +21,10 @@ Here's what a typical "day in the life" of a Zarf developer might look like. Kee
 
 :key: == Required by automation
 
-1. Pick an outstanding issue to work on, set yourself as the assignee, and move it to "Now" in the [Roadmap](https://github.com/defenseunicorns/zarf/projects/1). The "Next" and "Later" columns are mostly prioritized according to feedback from our users and other inputs, but don't feel like you have to pick from the top of the pile if something else is jumping out at you.
+1. Pick an outstanding issue to work on, set yourself as the assignee, and move it to "Doing Now" in the [Kanban Board](https://github.com/orgs/defenseunicorns/projects/1). The "Ready to Start" and "Planned" columns are mostly prioritized according to feedback from our users and other inputs, but don't feel like you have to pick from the top of the pile if something else is jumping out at you.
 1. Write up a rough outline of what you plan to do in the issue so you can get early feedback. Clearly announce any breaking changes you think need to be made.
 1. :key: Set up your Git config to GPG sign all commits. [Here's some documentation on how to set it up](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). You won't be able to merge your PR if you have any unverified commits.
-1. :key: Create a branch off the trunk, or a fork if you don't have the right permissions to push a branch.
+1. :key: Create a branch off the trunk, or a fork if you are an external contributor.
 1. Create a Draft Pull Request as soon as you are able to, even if it is just 5 minutes after you started working on it. Around here we aren't afraid to show unfinished work. It helps us get feedback more quickly.
 1. :key: Create a Pull Request (or mark it Ready for Review if you've been working in a Draft PR).
 1. :key: Run all automated tests by adding `/test all` as a comment in the PR. If you want to re-run certain tests you can also run them individually. Example: `/test e2e` just runs the end-to-end tests. You can chain different tests together like `/test foo bar baz`. You need `write` permission to the repo to trigger the tests.
@@ -40,7 +40,7 @@ This section dives deeper into how we test Zarf
 
 ### Pre-Commit Hooks and Linting
 
-In this repo we use [pre-commit](https://pre-commit.com/) hooks for automated validation and linting. The CI pipeline will validate that all of the hooks pass so we strongly recommend that you install the hooks locally or you'll be spending a lot of time manually fixing issues that could be fixed automatically very quickly.
+In this repo we use [pre-commit](https://pre-commit.com/) hooks for automated validation and linting. The CI pipeline will (eventually) validate that all of the hooks pass so we strongly recommend that you install the hooks locally or you'll be spending a lot of time manually fixing issues that could be fixed automatically very quickly.
 
 #### Pre-Commit Prerequisites
 
@@ -64,3 +64,31 @@ We're still working on building out the test suite. If you want to help check ou
 - [#100](https://github.com/defenseunicorns/zarf/issues/100): Each test should be runnable locally
 - [#101](https://github.com/defenseunicorns/zarf/issues/101): Run E2E tests on multiple distros
 - [#102](https://github.com/defenseunicorns/zarf/issues/102): Make the E2E tests more efficient
+
+## Documentation
+
+In this section you'll find documentation on documentation! Pun absolutely intended :smile:
+
+### Architecture Decision Records (ADR)
+
+We've chosen to use ADRs to document architecturally significant decisions. We primarily use the guidance found in [this article by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) with a couple of tweaks:
+
+- The criteria for when an ADR is needed is undefined. The team will decide when the team needs an ADR.
+- We will use the tool [adr-tools](https://github.com/npryce/adr-tools) to make it easier on ourselves to create and maintain ADRs.
+- We will keep ADRs in the repository under `docs/adr/NNNN-name-of-adr.md`. `adr-tools` is configured with a dotfile to automatically use this directory and format.
+
+### How to use `adr-tools`
+
+```bash
+# Create a new ADR titled "Use Bisquick for all waffle making"
+adr new Use Bisquick for all waffle making
+
+# Create a new ADR that supercedes a previous one. Let's say for example that the previous ADR about Bisquick was ADR number 9.
+adr new -s 9 Use scratch ingredients for all waffle making
+
+# Create a new ADR that amends a previous one. Let's say the previous one was ADR number 15
+adr new -l "15:Amends:Amended by" Use store-bought butter for all waffle making
+
+# Get full help docs. There are all sorts of other helpful commands that help manage the decision log.
+adr help
+```

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,23 @@
+# 1. Record architecture decisions
+
+Date: 2022-03-01
+
+## Status
+
+Accepted
+
+## Context
+
+> NOTE:
+>
+> This file was automatically created when we used [adr-tools](https://github.com/npryce/adr-tools) to initialize the document log in the repo. ADRs on ADRs are a little silly, but it does give a lightweight way to direct the reader over to our contributor guide that has a lot more information.
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions), with a couple of small tweaks. See the [Documentation section in the Contributor guide](../../CONTRIBUTING.md#documentation) for full details.
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

docs/adr/template.md

@@ -0,0 +1,19 @@
+# NUMBER. TITLE
+
+Date: DATE
+
+## Status
+
+STATUS
+
+## Context
+
+The issue motivating this decision, and any context that influences or constrains the decision.
+
+## Decision
+
+The change that we're proposing or have agreed to implement.
+
+## Consequences
+
+What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.