diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..aae2c68 --- /dev/null +++ b/Makefile @@ -0,0 +1,4 @@ +gentoc: + ./generate_toc.sh > TOC.md + +default: gentoc diff --git a/README.md b/README.md index f79efe8..bd560aa 100644 --- a/README.md +++ b/README.md @@ -76,14 +76,15 @@ $ adr-viewer --help Using adr-tools cli (adr): -### set adr-tools directory for team in question: -See the limitations of adr-tools notation above. You need to change `.adr-dir` to the team you want to work on. -``` -$ echo "decisions/websre" > .adr-dir -``` +To handle multiple teams we've made the table of contents generator work just on filenames. +As such you can generally treat each adr directory as independent from the point of view of the ADR CLI tool. ### create new adr proposal for your team: +This assumes someone has initialized a team or group folder for you previously. +If not, the info is below. + ``` +$ cd decisions/$team $ adr new My Awesome Web SRE Team ADR ./0002-my-awesome-global-adr.md # then add your info & go @@ -91,9 +92,16 @@ $ vi 0002-my-awesome-global-adr.md ``` ### initialize a new team- or group-specific decisions directory: + +You'll need a new folder for your team, feel free to add as needed. +You will need to force add the adr-dir, as we want to ignore it at the root of repo, +but it's nice to have, to make the init/new commands work well. + ``` -$ adr init decisions/my-new-team - decisions/my-new-team/0001-record-architecture-decisions.md +$ mkdir -p decisions/$team +$ cd decisions/$team +$ echo "." > .adr-dir +$ git add -f .adr-dir $ vi decisions/my-new-team/0001-record-architecture-decisions.md # then add your info & go $ cp -r decisions/websre/templates decisions/my-new-team # set up custom templates if you like $ vi decisions/my-new-team/templates/template.md # edit that custom team template @@ -101,8 +109,9 @@ $ vi decisions/my-new-team/templates/template.md # edit that custom team templat ### generate whole repository Table of Contents: ``` -$ adr generate toc > TOC.md -# need to add some recursion when using more than Web SRE Team decisions. +$ make gentoc +# this will run the custom script generate_toc.sh, and generate the table of contents into the TOC.md file +# commit this to git if you'd like. ``` For a cleaner presentation, adr-viewer (a python package) is being considered as part of the CI to generate static files for a website from this repository. diff --git a/TOC.md b/TOC.md index e4553c5..af4c557 100644 --- a/TOC.md +++ b/TOC.md @@ -1,5 +1,11 @@ # Architecture Decision Records -* [1. Record architecture decisions](0001-record-architecture-decisions.md) -* [2. Web SRE Service Documentation](0002-web-sre-service-documentation.md) -* [3. Use EKS Cluster as Default Container Platform](0003-use-eks-cluster-as-default-container-platform.md) + +## websre +* [1. Record architecture decisions](./decisions/websre/0001-record-architecture-decisions.md) +* [2. Web SRE Service Documentation](./decisions/websre/0002-web-sre-service-documentation.md) +* [3. Use EKS Cluster as Default Container Platform](./decisions/websre/0003-use-eks-cluster-as-default-container-platform.md) + + +## global +* [1. Record architecture decisions](./decisions/global/0001-record-architecture-decisions.md) diff --git a/decisions/global/.adr-dir b/decisions/global/.adr-dir new file mode 100644 index 0000000..9c558e3 --- /dev/null +++ b/decisions/global/.adr-dir @@ -0,0 +1 @@ +. diff --git a/decisions/global/0001-record-architecture-decisions.md b/decisions/global/0001-record-architecture-decisions.md new file mode 100644 index 0000000..2d16cbc --- /dev/null +++ b/decisions/global/0001-record-architecture-decisions.md @@ -0,0 +1,27 @@ +# 1. Record architecture decisions + +Date: 2021-04-28 +Scope: Web SRE Team + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made for our team. + +## Decision + +We will use Architecture Decision Records, as discussed in our original proposal: https://docs.google.com/document/d/1pZlYCyXcZbmQq1O-g4BNJD1uZTjluYKkk7BSu2BwOGU/edit# + +## Consequences + +* add ADR proposal and review planning to our team planning meetings +* may slow down / stop immediately jumping into some projects to make time for proactive architectural review + +## Resources + +* originating JIRA ticket: https://jira.mozilla.com/browse/SE-1670 +* The original proposal google doc: https://docs.google.com/document/d/1pZlYCyXcZbmQq1O-g4BNJD1uZTjluYKkk7BSu2BwOGU/edit# +* [Michael Nygard's article](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) diff --git a/decisions/websre/.adr-dir b/decisions/websre/.adr-dir new file mode 100644 index 0000000..9c558e3 --- /dev/null +++ b/decisions/websre/.adr-dir @@ -0,0 +1 @@ +. diff --git a/generate_toc.sh b/generate_toc.sh new file mode 100755 index 0000000..e035209 --- /dev/null +++ b/generate_toc.sh @@ -0,0 +1,45 @@ +#!/bin/bash +set -e + +args=$(getopt i:o:p: $*) +set -- $args + +link_prefix=./decisions/ + +eval "$(adr config)" + +cat <