Skip to content
/ adr Public

Architecture Decision Records in Node.js with Reporter, supported Windows, GNU/Linux, macOS - 轻量级架构决策记录工具

License

Notifications You must be signed in to change notification settings

phodal/adr

Repository files navigation

ADR - Architecture Decision Records(轻量级架构决策记录工具)

ADR - Architecture Decision Records(轻量级架构决策记录工具)

Build Status codecov.io Maintainability

Markdown Improve node npm

Inspired by https://github.com/npryce/adr-tools, but supported Windows.

ADR Blogpost: Documenting Architecture Decisions

A good material about Architecture decision record

中文翻译:架构决策记录

功能特性

  • 支持 Windows, GNU/Linux, Mac OS
  • Markdown 目录生成
  • 为项目经理、业务人员等非开发人员,生成报表:HTML,CSV, JSON
  • 兼容 adr-tools
  • 国际化支持:English、中文、Brazilian Portuguese (pt-br), Standard Italian (it-IT)
  • 状态历史
  • 状态查询
  • 更好的列表展示
  • 兼容 adr-tools

查看本项目的架构决策记录

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
  • 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

Screenshots

ADR List

List Examples

ADR Reporter

Reporter Examples

Install

  1. install
npm install -g adr
  1. init
adr init <language>

e.x: adr init en

new

adr new <decision>

e.x: adr new "create project". It will open the new file with your config editor

list

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

adr generate toc

results:

# Architecture Decision Records

* [1. 编写完整的单元测试](001-编写完整的单元测试.md)
* [2. 添加目录生成](002-添加目录生成.md)
* [3. 图形生成](003-图形生成.md)

generate graph

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

adr update

decisions change logs

adr logs <index>

e.x. adr logs 9

╔════════════╤══════╗
║  -         │  -   ║
╟────────────┼──────╢
║ 2017-11-23 │ 提议 ║
╟────────────┼──────╢
║ 2017-11-24 │ 通过 ║
╚════════════╧══════╝

export adr

support: json, csv, html, markdown

adr export <type>

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

adr search <keyword>

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, 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) oradoc for asciidoc

example config:

{
  "path":"doc/adr/",
  "language":"zh-cn",
  "prefix": "",
  "digits": 4,
  "editor": "code",
  "force_nfc": true,
  "extension": "md"
}

License

Phodal's Idea

@ 2017~2021 A Phodal Huang's Idea. This code is distributed under the MIT license. See LICENSE in this directory.