From 9666031db1d142ddd8d05f0acdab815bfbf60cce Mon Sep 17 00:00:00 2001 From: Jennifer Power Date: Fri, 9 Aug 2024 13:48:33 -0400 Subject: [PATCH] docs: updates tool for ADR management to trestle (#316) * docs: updates tools for ADR management to trestle Signed-off-by: Jennifer Power * docs: updates decisions template to make default status proposed Signed-off-by: Jennifer Power --------- Signed-off-by: Jennifer Power --- .adr-dir | 1 - .github/workflows/validate-adrs.yml | 27 +++++++++++++++++++ CONTRIBUTING.md | 6 ++++- docs/architecture/.trestle/.keep | 0 .../author/decisions/0.0.1/template.md | 17 ++++++++++++ .../0001-record-architecture-decisions.md | 19 ------------- .../record-architecture-decisions_000.md | 17 ++++++++++++ 7 files changed, 66 insertions(+), 21 deletions(-) delete mode 100644 .adr-dir create mode 100644 .github/workflows/validate-adrs.yml create mode 100644 docs/architecture/.trestle/.keep create mode 100644 docs/architecture/.trestle/author/decisions/0.0.1/template.md delete mode 100644 docs/architecture/decisions/0001-record-architecture-decisions.md create mode 100644 docs/architecture/decisions/record-architecture-decisions_000.md diff --git a/.adr-dir b/.adr-dir deleted file mode 100644 index da5cac6b..00000000 --- a/.adr-dir +++ /dev/null @@ -1 +0,0 @@ -docs/architecture/decisions diff --git a/.github/workflows/validate-adrs.yml b/.github/workflows/validate-adrs.yml new file mode 100644 index 00000000..051d675e --- /dev/null +++ b/.github/workflows/validate-adrs.yml @@ -0,0 +1,27 @@ + +name: Validate ADRs + +on: + pull_request: + branches: + - main + paths: + - 'docs/architecture/decisions' + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - name: Checkout Code + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # pin@v4 + + - name: Set up poetry and install + uses: ./.github/actions/setup-poetry + with: + python-version: '3.11' + + - name: Run validate adrs + run: trestle author docs validate -tn decisions -hv -tr docs/architecture + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdceb3e5..1b2d068d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,7 +83,11 @@ For workflow diagrams, see the [diagrams](./docs/workflows/) under the `docs` fo #### Architecture Decisions -We document decisions using [Architectural Decision Records](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions). The team will decide when an ADR will be put in place, but this is generally done to document impactful architectural decisions. [`adr-tools`](https://github.com/npryce/adr-tools) can be used to manage ADRs in the repository located under `docs/architecture/decisions`. +We document decisions using [Architectural Decision Records](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). The team will decide when an ADR will be put in place, but this is generally done to document impactful architectural decisions. + +* Create an instance of the ADR template using `trestle author docs create-sample -tn decisions -tr docs/architecture`. +* This can be tested locally via `trestle author docs validate --task-name decisions -hv -tr docs/architecture` + #### Update the `actions` files diff --git a/docs/architecture/.trestle/.keep b/docs/architecture/.trestle/.keep new file mode 100644 index 00000000..e69de29b diff --git a/docs/architecture/.trestle/author/decisions/0.0.1/template.md b/docs/architecture/.trestle/author/decisions/0.0.1/template.md new file mode 100644 index 00000000..ea75602e --- /dev/null +++ b/docs/architecture/.trestle/author/decisions/0.0.1/template.md @@ -0,0 +1,17 @@ +--- +x-trestle-template-version: 0.0.1 +title: +status: proposed # Valid statuses are proposed, deferred, rejected, withdrawn or replaced +--- + +## Context + + + +## Decision + + + +## Consequences + + \ No newline at end of file diff --git a/docs/architecture/decisions/0001-record-architecture-decisions.md b/docs/architecture/decisions/0001-record-architecture-decisions.md deleted file mode 100644 index 60d0d489..00000000 --- a/docs/architecture/decisions/0001-record-architecture-decisions.md +++ /dev/null @@ -1,19 +0,0 @@ -# 1. Record architecture decisions - -Date: 2024-07-30 - -## Status - -Accepted - -## Context - -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). - -## 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). diff --git a/docs/architecture/decisions/record-architecture-decisions_000.md b/docs/architecture/decisions/record-architecture-decisions_000.md new file mode 100644 index 00000000..f9dc0fbf --- /dev/null +++ b/docs/architecture/decisions/record-architecture-decisions_000.md @@ -0,0 +1,17 @@ +--- +x-trestle-template-version: 0.0.1 +title: Record architecture decisions +status: accepted # Valid statuses are proposed, accepted, deferred, rejected, withdrawn, or replaced +--- + +## Context + +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). + +## Consequences + +See Michael Nygard's article, linked above. `trestle` will be used to create and validate these decisions.