Markdown 架构决策记录

“Markdown 架构决策记录”（MADR）[ˈmæɾɚ] – 那些重要的 [ˈmæɾɚ] 决策。

快速入门

adr-template.md 包含所有部分，并附有相关说明。
adr-template-minmal.md 仅包含必需部分，并附有相关说明。
adr-template-bare.md 包含所有部分，均为空（无说明）。
adr-template-bare-minimal.md 包含必需部分，无说明。

将其复制到 docs/decisions。对于每个 ADR，将模板复制到 nnnn-title.md 并进行调整。更详细的说明：请前往 https://adr.github.io/madr/#applying-madr-to-your-project。

开发提示

MADR 遵循 Semantic Versioning 2.0.0，并在 CHANGELOG.md 中记录变更，遵循 keep a changelog 1.0.0。
问题可在 https://github.com/adr/madr/issues 报告。
建议可通过 pull request 提交。MADR 提供预配置的 VS Code web 环境，位于 Gitpod。
MADR 使用 markdownlint 作为 Markdown 文件的 Linter。在 VS Code 中检查 linting 问题时，请使用 markdownlint。
template/adr-template.md 已镜像至 docs/decisions/adr-template。然而，添加了以下 YAML front matter，以便 Just the Docs Jekyll Template 正确处理。
```
---
parent: Decisions
nav_order: 100
title: ADR Template
---
```

分支

分支	含义
`gh-pages`	展示最新已发布版本的主页，渲染于 https://adr.github.io/madr
`develop`	最新开发内容，包括应在发布时发布的主页更新。`gh-pages` 应始终合并到此分支。
`release/vY`	MADR 最新 Y.x 版本发布分支。引入以修复 #92

分支命名约定遵循 git flow 模型。

另见 CONTRIBUTING.md。

引用 MADR

要在您的科学工作中引用 MADR，请使用以下引用：

@InProceedings{Kopp2018,
  author    = {Kopp, Oliver and Armbruster, Anita and Zimmermann, Olaf},
  booktitle = {ZEUS},
  title     = {Markdown Architectural Decision Records: Format and Tool Support},
  year      = {2018},
}

如何在本地启动 Jekyll

要渲染 docs 目录，需要 Jekyll。

对于本地开发，请遵循 Jekyll 安装说明。安装最新版本的 ruby 后，再执行 gem install bundler 即可。

之后，运行

bundle install
jekyll serve --livereload

并在浏览器中访问 http://localhost:4000/madr/。

在 Windows 上，建议使用容器化环境：

docker run -p 4000:4000 --rm -v "C:\git-repositories\adr.github.io\madr\docs":/site bretfisher/jekyll-serve

如果您遇到与 Gemfile.lock 相关的错误，只需删除 Gemfile.lock 并重新运行。

更新 just-the-docs

调整 docs/Gemfile 以使用更新版本的 just-the-docs。因此，请检查 https://github.com/just-the-docs/just-the-docs-template/blob/main/Gemfile 以获取版本信息。
删除 docs/Gemfile.lock。启动 bundle install。
检查 https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md。
检查 https://just-the-docs.com/migration/。

发布新版本

更新 docs/index.md 和 docs/examples.md 中的示例。
使用新模板更新 docs/decisions/* 中的具体决策。
提交（"Update examples and decisions"）并推送。可能作为拉取请求。
调整 template/0000-use-markdown-architectural-decision-records.md 中的版本引用。
更新 docs/decisions 中的 "template" 文件：
- 将 template/0000-use-markdown-architectural-decision-records.md 复制到 docs/decisions/0000-use-markdown-architectural-decision-records.md。
- 根据 template/adr-template.md 调整 docs/decisions/adr-template.md 的内容。因此，确保保留 docs/decisions/adr-template.md 中的 YAML front matter。
在 "Older versions"（用于主页）处添加指向 docs/index.md 的链接。
将 .markdownlint.yml 复制到 template/.markdownlint.yml（以及可能复制到 docs/.markdownlint.yml）。
更新 CHANGELOG.md。
提交。
更新 package.json 并使用 release-it 发布到 npmjs（不要在 GitHub 上创建发布）。这也会执行一次提交。
使用 github-release-from-changelog 创建 GitHub 发布。
将 develop 合并到 gh-pages

许可证

本作品在 MIT 和 CC0 下双重授权。如果您使用本作品，可以选择其中之一。

SPDX-License-Identifier: MIT OR CC0-1.0