From fc2e8cffab3b94e46c54158a17e8276d90c9cb8c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Tue, 17 May 2022 00:43:55 +0200 Subject: [PATCH] Add "Using in large projects" (and switch from * to - list style) --- docs/decisions/0010-support-categories.md | 2 +- docs/index.md | 62 ++++++++++++++++------- 2 files changed, 46 insertions(+), 18 deletions(-) diff --git a/docs/decisions/0010-support-categories.md b/docs/decisions/0010-support-categories.md index dab319e..f0483fd 100644 --- a/docs/decisions/0010-support-categories.md +++ b/docs/decisions/0010-support-categories.md @@ -53,7 +53,7 @@ Use Angular ![category-frontend](https://img.shields.io/badge/category-frontend- * Good, because straight-forward to parse * Bad, because no simple filtering using `ls` or Windows Explorer is possible -### Use YAML frontmatter +### Use YAML frontmatter Example: diff --git a/docs/index.md b/docs/index.md index a097f19..457f665 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,23 +11,25 @@ The template originated from capturing architectural decisions and developed to **Note that this documentation describes MADR 3.0.0-alpha (not yet released) and might not apply to earlier released versions** -- [News](#news) -- [Overview](#overview) -- [Example](#example) -- [Apply it to your project](#apply-it-to-your-project) - - [Initialization](#initialization) - - [Create a new ADR](#create-a-new-adr) - - [Lint ADRs](#lint-adrs) -- [License](#license) +* [News](#news) +* [Overview](#overview) +* [Example](#example) +* [Apply it to your project](#apply-it-to-your-project) + * [Initialization](#initialization) + * [Create a new ADR](#create-a-new-adr) + * [Lint ADRs](#lint-adrs) +* [Using in large projects](#using-in-large-projects) + * [Usage of categories](#usage-of-categories) +* [License](#license) ## News -- 2021-04-25: MADR examples featured in Medium stories ["From Architectural Decisions to Design Decisions"](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and ["ADR = Any Decision Record?"](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) -- 2021-04-08: MADR recommended as an ADR format in "Design Practice Repository". This ebook is available on [Leanpub](https://leanpub.com/dpr). The decision capturing activity is also described [online](https://socadk.github.io/design-practice-repository/activities/DPR-ArchitecturalDecisionCapturing.html). -- 2020-09-29: MADR presented in the keynote "Markdown Architectural Decision Records: Capturing Decisions Where the Developer is Working" at the workshop "[Second Software Documentation Generation Challenge (DocGen2)](https://dysdoc.github.io/docgen2/index.html)". Slides available at [Speaker Deck](https://speakerdeck.com/koppor/markdown-architecturaldecisionrecords-capturing-decisions-where-the-developer-is-working). -- 2019-07-08: MADR referenced in [Architectural Decisions — The Making Of](https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html), a post in the new blog "The Concerned Architect" by Olaf Zimmermann (shorter version available on [Medium](https://medium.com/@docsoc/y-statements-10eb07b5a177)). -- 2018-04-13: Mentioned in [@vanto](https://github.com/vanto)'s presentation about ADRs: . -- 2018-04-03: Scientific publication: [Markdown Architectural Decision Records: Format and Tool Support](http://ceur-ws.org/Vol-2072/paper9.pdf). +* 2021-04-25: MADR examples featured in Medium stories ["From Architectural Decisions to Design Decisions"](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and ["ADR = Any Decision Record?"](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) +* 2021-04-08: MADR recommended as an ADR format in "Design Practice Repository". This ebook is available on [Leanpub](https://leanpub.com/dpr). The decision capturing activity is also described [online](https://socadk.github.io/design-practice-repository/activities/DPR-ArchitecturalDecisionCapturing.html). +* 2020-09-29: MADR presented in the keynote "Markdown Architectural Decision Records: Capturing Decisions Where the Developer is Working" at the workshop "[Second Software Documentation Generation Challenge (DocGen2)](https://dysdoc.github.io/docgen2/index.html)". Slides available at [Speaker Deck](https://speakerdeck.com/koppor/markdown-architecturaldecisionrecords-capturing-decisions-where-the-developer-is-working). +* 2019-07-08: MADR referenced in [Architectural Decisions — The Making Of](https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html), a post in the new blog "The Concerned Architect" by Olaf Zimmermann (shorter version available on [Medium](https://medium.com/@docsoc/y-statements-10eb07b5a177)). +* 2018-04-13: Mentioned in [@vanto](https://github.com/vanto)'s presentation about ADRs: . +* 2018-04-03: Scientific publication: [Markdown Architectural Decision Records: Format and Tool Support](http://ceur-ws.org/Vol-2072/paper9.pdf). ## Overview @@ -110,9 +112,9 @@ As a consequence, some existing tooling might not be applicable. The filenames are following the pattern `NNNN-title-with-dashes.md` ([ADR-0005](docs/decisions/0005-use-dashes-in-filenames.md)), where -- `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository. -- the title is stored using dashes and lowercase, because [adr-tools] also does that. -- the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file. +* `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository. +* the title is stored using dashes and lowercase, because [adr-tools] also does that. +* the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file. Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation. @@ -129,6 +131,32 @@ There is an initial configuration for it at `template/.markdownlint`. You can use that configuration in a GitHub workflow. See [`.github/workflows/lint.yaml`](.github/workflows/lint.yaml) for an example. +## Using in large projects + +Large projects may have hunders decision records, where finding them might be hard. +MADR does not enforce any repository or directory organization structure. +In the following proposals from the community are presented + +### Usage of categories + +However, MADR leans forward to categorize ADRs using sub directories and put the ADRs into these sub folders. + +Example folder structure could be as follows: + +```tree +. +`-- decisions + |-- backend + | |-- 0001-use-quarkus.md + `-- ui + `-- 0001-use-vuejs.md +``` + +With this approach, all categories are explicit, because the sub directories define the catories. +It is accepted, that numbers of ADRs are not unique throughout the repository any more, but local for a category. + +Note that other alternatives are discussed at [ADR-0010](decisions/0010-support-categories.md). + ## License This work is dual-licensed under [MIT](https://opensource.org/licenses/MIT) and