https://github.com/phodal/adr
Architecture Decision Records in Node.js with Reporter, supported Windows, GNU/Linux, macOS - 轻量级架构决策记录工具
https://github.com/phodal/adr
adr architecture-decision architecture-decision-records architecture-doc architecture-guidelines architecture-visualization decision-records
Last synced: 2 days ago
JSON representation
Architecture Decision Records in Node.js with Reporter, supported Windows, GNU/Linux, macOS - 轻量级架构决策记录工具
- Host: GitHub
- URL: https://github.com/phodal/adr
- Owner: phodal
- License: mit
- Created: 2017-11-22T02:02:30.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-30T01:19:53.000Z (9 months ago)
- Last Synced: 2025-04-08T15:06:20.755Z (about 1 month ago)
- Topics: adr, architecture-decision, architecture-decision-records, architecture-doc, architecture-guidelines, architecture-visualization, decision-records
- Language: TypeScript
- Homepage: https://phodal.github.io/adr/
- Size: 3.01 MB
- Stars: 267
- Watchers: 7
- Forks: 52
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
ADR - Architecture Decision Records（轻量级架构决策记录工具）
===
> ADR - Architecture Decision Records（轻量级架构决策记录工具）
[](https://travis-ci.org/phodal/adr) [](https://codecov.io/github/phodal/adr?branch=master) [](https://codeclimate.com/github/phodal/adr/maintainability)
[](https://github.com/phodal/markdown-improve) [](https://www.npmjs.com/package/adr) [](https://www.npmjs.com/adr)
Inspired by [https://github.com/npryce/adr-tools](https://github.com/npryce/adr-tools), but supported Windows.
ADR Blogpost: [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)
A good material about [Architecture decision record](https://github.com/joelparkerhenderson/architecture_decision_record)
中文翻译：[架构决策记录](https://www.phodal.com/blog/documenting-architecture-decisions/)
**功能特性**
- 支持 Windows, GNU/Linux, Mac OS
- Markdown 目录生成
- 为项目经理、业务人员等非开发人员，生成报表：HTML，CSV, JSON
- 兼容 adr-tools
- 国际化支持：English、中文、Brazilian Portuguese (pt-br), Standard Italian (it-IT)
- 状态历史
- 状态查询
- 更好的列表展示
- 兼容 adr-tools
[查看本项目的架构决策记录](/docs/adr)
**Features**
- Supported Windows, GNU/Linux, Mac OS
- **report for PM, BA**: html, csv, json
- Support Markdown and Asciidoc
- generate markdown and asciidoc toc（see in [docs/adr](/docs/adr) ）
- **i18n**: English (en), 中文(zh-cn), Brazilian Portuguese (pt-br), Standard Italian (it-IT), Farsi (fa), French (fr)
- status logs
- status query
- better list view
- compatible adr-tools
- custom templates: add a `template.md` (or `template.adoc`, `template.asciidoc`) file in the save path
## HTML Reporter Example
- [ADR Example](https://phodal.github.io/adr/examples/export-1.html)
- [ADR Tools Example](https://phodal.github.io/adr/examples/export-3.html)
- [会分期 Example](https://phodal.github.io/adr/examples/export-2.html)
- [Arachne Framework Example](https://phodal.github.io/adr/examples/export-4.html)
Screenshots
---
### ADR List
### ADR Reporter
## Install
1. install
```bash
npm install -g adr
```
2. init
```bash
adr init
```
e.x: ``adr init en``
### new
```bash
adr new
```
e.x: ``adr new "create project"``. It will open the new file with your config [editor](#config)
### list
```bash
adr list
```
result:
```
╔══════════════════════════════════════╤══════════════╤═══════════════════╗
║ Decision │ Last Modified│ Last Status ║
╟──────────────────────────────────────┼──────────────┼───────────────────╢
║ 1.编写完整的单元测试 │ 2017-11-26 │ 2017-11-26 已完成 ║
╟──────────────────────────────────────┼──────────────┼───────────────────╢
║ 2.添加目录生成 │ 2017-11-26 │ 2017-11-25 已完成 ║
╟──────────────────────────────────────┼──────────────┼───────────────────╢
║ 3.图形生成功能 │ 2017-11-26 │ 2017-11-24 已完成 ║
╟──────────────────────────────────────┼──────────────┼───────────────────╢
║ 4.生成在线图形 │ 2017-11-26 │ 2017-11-22 提议 ║
╚══════════════════════════════════════╧══════════════╧═══════════════════╝
```
### generate toc
```bash
adr generate toc
```
results:
```markdown
# Architecture Decision Records
* [1. 编写完整的单元测试](001-编写完整的单元测试.md)
* [2. 添加目录生成](002-添加目录生成.md)
* [3. 图形生成](003-图形生成.md)
```
### generate graph
```sh
adr generate graph
```
results:
```
digraph {
node [shape=plaintext];
_1 [label="1.编写完整的单元测试"; URL="001-编写完整的单元测试.md"]
_2 [label="2.添加目录生成"; URL="002-添加目录生成.md"]
_1 -> _2 [style="dotted"];
_3 [label="3.图形生成"; URL="003-图形生成.md"]
_2 -> _3 [style="dotted"];
}
```
### update filename by title
```bash
adr update
```
### decisions change logs
```bash
adr logs
```
e.x. ``adr logs 9``
```
╔════════════╤══════╗
║ - │ - ║
╟────────────┼──────╢
║ 2017-11-23 │ 提议 ║
╟────────────┼──────╢
║ 2017-11-24 │ 通过 ║
╚════════════╧══════╝
```
### export adr
support: json, csv, html, markdown
```bash
adr export
```
e.x. ``adr export csv``
```
Index, 决策, 上次修改时间, 最后状态
1, 编写完整的单元测试, 2017-11-26, 2017-11-26 已完成
2, 添加目录生成, 2017-11-26, 2017-11-25 已完成
3, 图形生成功能, 2017-11-26, 2017-11-24 已完成
```
### search adr
```bash
adr search
```
e.x. ``adr search 测试``
```
╔══════════════════════╤══════════════════╗
║ 决策 │ 最后状态 ║
╟──────────────────────┼──────────────────╢
║ 19.添加-e2e-测试 │ 2017-11-28 提议 ║
╟──────────────────────┼──────────────────╢
║ 1.编写完整的单元测试 │ 2017-11-26 完成 ║
╚══════════════════════╧══════════════════╝
```
Config
---
current:
- **language**, language
- **path**, save path
- **digits**, the index length, e.x. digits:3 001-index.md
- **prefix**, the prefix of files, e.x. adr-0001
- **editor**, the editor to open file, e.x. code, [more information](https://github.com/lahmatiy/open-in-editor#editor), and you can also use the editor by setting the program path, such as `/System/Applications/TextEdit.app/Contents/MacOS/TextEdit`
- **force_nfc**, whether to normalize the names of files generated by `adr` commands in NFC (Normalization Form Canonical Composition) format, e.x. `true`
- **extension**, the document extension/format you want to used. `md` for Markdown (default value) or`adoc` for asciidoc
example config:
```json
{
"path":"doc/adr/",
"language":"zh-cn",
"prefix": "",
"digits": 4,
"editor": "code",
"force_nfc": true,
"extension": "md"
}
```
License
---
[](http://ideas.phodal.com/)
@ 2017~2021 A [Phodal Huang](https://www.phodal.com)'s [Idea](http://github.com/phodal/ideas). This code is distributed under the MIT license. See `LICENSE` in this directory.