From cf7bcbb3c21172bc7e064bf94b9e72cb6fcd9d96 Mon Sep 17 00:00:00 2001 From: Jennifer Power Date: Tue, 6 Aug 2024 16:14:54 -0400 Subject: [PATCH 1/2] docs: updates tools for ADR management to trestle 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 ++++++++++++ ...d => record-architecture-decisions_000.md} | 14 +++++----- 6 files changed, 55 insertions(+), 10 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 rename docs/architecture/decisions/{0001-record-architecture-decisions.md => record-architecture-decisions_000.md} (50%) 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..1e50962a --- /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: accepted #Valid statuses are 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/record-architecture-decisions_000.md similarity index 50% rename from docs/architecture/decisions/0001-record-architecture-decisions.md rename to docs/architecture/decisions/record-architecture-decisions_000.md index 60d0d489..10b49cb1 100644 --- a/docs/architecture/decisions/0001-record-architecture-decisions.md +++ b/docs/architecture/decisions/record-architecture-decisions_000.md @@ -1,10 +1,8 @@ -# 1. Record architecture decisions - -Date: 2024-07-30 - -## Status - -Accepted +--- +x-trestle-template-version: 0.0.1 +title: Record architecture decisions +status: accepted #Valid statuses are deferred, rejected, withdrawn or replaced +--- ## Context @@ -16,4 +14,4 @@ We will use Architecture Decision Records, as [described by Michael Nygard](http ## 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). +See Michael Nygard's article, linked above. `trestle` will be used to create and validate these decisions. From 91659cde7c19fe8079ef5a785b59b6192ddfc080 Mon Sep 17 00:00:00 2001 From: Jennifer Power Date: Wed, 7 Aug 2024 17:30:30 -0400 Subject: [PATCH 2/2] docs: updates decisions template to make default status proposed Signed-off-by: Jennifer Power --- docs/architecture/.trestle/author/decisions/0.0.1/template.md | 2 +- .../architecture/decisions/record-architecture-decisions_000.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/.trestle/author/decisions/0.0.1/template.md b/docs/architecture/.trestle/author/decisions/0.0.1/template.md index 1e50962a..ea75602e 100644 --- a/docs/architecture/.trestle/author/decisions/0.0.1/template.md +++ b/docs/architecture/.trestle/author/decisions/0.0.1/template.md @@ -1,7 +1,7 @@ --- x-trestle-template-version: 0.0.1 title: -status: accepted #Valid statuses are deferred, rejected, withdrawn or replaced +status: proposed # Valid statuses are proposed, deferred, rejected, withdrawn or replaced --- ## Context diff --git a/docs/architecture/decisions/record-architecture-decisions_000.md b/docs/architecture/decisions/record-architecture-decisions_000.md index 10b49cb1..f9dc0fbf 100644 --- a/docs/architecture/decisions/record-architecture-decisions_000.md +++ b/docs/architecture/decisions/record-architecture-decisions_000.md @@ -1,7 +1,7 @@ --- x-trestle-template-version: 0.0.1 title: Record architecture decisions -status: accepted #Valid statuses are deferred, rejected, withdrawn or replaced +status: accepted # Valid statuses are proposed, accepted, deferred, rejected, withdrawn, or replaced --- ## Context