Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add "Using in large projects" #58

Merged
merged 1 commit into from
May 16, 2022
Merged

Add "Using in large projects" #58

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/decisions/0010-support-categories.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
62 changes: 45 additions & 17 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,23 +11,25 @@ The template originated from capturing architectural decisions and developed to
<!-- markdownlint-disable-file MD036-->
**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) <!-- and blog post ["ADR = Any Decision Record? Architecture, Design and Beyond"](https://ozimmer.ch/practices/2021/04/23/AnyDecisionRecords.html) -->
- 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: <https://speakerdeck.com/vanto/a-brief-introduction-to-architectural-decision-records>.
- 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) <!-- and blog post ["ADR = Any Decision Record? Architecture, Design and Beyond"](https://ozimmer.ch/practices/2021/04/23/AnyDecisionRecords.html) -->
* 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: <https://speakerdeck.com/vanto/a-brief-introduction-to-architectural-decision-records>.
* 2018-04-03: Scientific publication: [Markdown Architectural Decision Records: Format and Tool Support](http://ceur-ws.org/Vol-2072/paper9.pdf).

## Overview

Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand Down