あるプロジェクトでの議論中に「あれ、これ以前どう決めましたっけ?」と言うときがあった
議事メモもとっていたけど、日付をタイトルにとっていたため
あれはいつのことだったか?とジジイのようなことを言って時間を費やしてしまった
意思決定したことをどう残していったらよいのかと考えていたところ@kawasimaさんよりADR(Architectural Decision Records)というものを教えてもらったので整理する
以下のドキュメントを引用、参考にする
- Documenting Architecture Decisions
- http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions · GitHub
- dapr/decision_records.md at master · dapr/dapr · GitHub
ADRとは
- Architecture Decision Recordsの略
- 重要なアーキテクチャ上の意思決定とそのコンテキストおよび結果を記録するための手法
- technology radarの中で"adopt"としている www.thoughtworks.com
書き方ポイント
- 小さくまとまりのあるドキュメントを心がける
- 将来の開発者との会話であるかのように記述する
将来の開発者が英語話すかもしれないから英語でかく(か迷う) - フォーマットで手短にテキストファイルに記録する
- プロジェクトのリポジトリの
doc/arch/adr-NNN.md
に配置する - Markdownのような軽量のテキストフォーマット言語を使用する
- 順番に番号を振り、再利用しないようにする
こんな感じがよさそう(dapr/daprより抜粋)
フォーマット
こんな感じ(dapr/daprより抜粋)
SDK-002: Java JDK Versions
Status
Accepted
Context
Dapr offers a Java SDK. Java 11 is the latest LTS version. Java 8 is the previous LTS version but still the mainly used version by the Java community in 2019. What should be the minimum Java version supported by Dapr's Java SDK?
See https://github.com/dapr/java-sdk/issues/17
Decisions
Java 8 should be the minimum version supported for Dapr's Java SDK. Java 11 should be used in samples and user documentation to encourage adoption. Java 8's commercial support ends in 2022. Dapr's Java SDK shoud migrate to Java 11 prior to that. The timeline still not decided.
Consequences
Customers running with Java 7 or below cannot use Dapr's Java SDK. Customers running with Java 8 are still supported, even through Java 11 is the recommended version. Modern language features will not be available in Dapr's Java SDK code. Modern JVM features can still be used since the Java 11 JVM can run Java 8 bytecode.
運用してみて、また後日感想をまとめる