这里用于记录 Cosmos Hub 中新功能与模块提案的所有高层架构决策。 架构决策（AD）是指为满足在架构层面具有重要意义的功能性或非功能性需求而做出的软件设计选择。 架构显著性需求（ASR）是指会对软件系统的架构和质量产生可衡量影响的需求。 架构决策记录（ADR）用于记录单个 AD，这种做法常见于个人笔记或会议纪要；一个项目中创建并持续维护的 ADR 集合共同构成其决策日志。以上内容都属于架构知识管理（AKM）的范畴。 你可以在这里进一步了解 ADR 概念。

​
背景与动机

ADR 旨在作为提出新功能设计与新流程的主要机制，用于收集社区对某个问题的意见，并记录设计决策。 一份 ADR 应当提供：
  • 相关目标与当前状态的背景信息
  • 为实现目标而提出的变更
  • 优缺点总结
  • 被放弃的方案空间以及放弃原因
  • 参考资料
  • 变更日志
请注意 ADR 与规范文档（spec）之间的区别。ADR 提供的是架构变更或某个全新架构的背景、直觉、推理与论证依据。规范文档则是对当前实际状态的更精炼、更直接的总结。 如果已记录的决策后来被证明不够充分，应召集讨论，在此记录新的决策，然后修改代码以与之保持一致。

​
创建新的 ADR

请阅读流程。

​
使用 RFC 2119 关键词

编写 ADR 时，应遵循与编写 RFC 相同的最佳实践。 编写 RFC 时，会使用关键词来表示规范中的要求。 这些词通常会使用大写形式：“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY” 和 “OPTIONAL”。 它们的解释应以 RFC 2119 中的定义为准。

​
ADR 目录

​
已接受

  • 无

​
已提议

​
草稿

  • 无

​
已拒绝

​
已弃用

This is a location to record all high-level architecture decisions for new feature and module proposals in the Cosmos Hub. An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM). You can read more about the ADR concept here.

​
Rationale

ADRs are intended to be the primary mechanism for proposing new feature designs and new processes, for collecting community input on an issue, and for documenting the design decisions. An ADR should provide:
  • Context on the relevant goals and the current state
  • Proposed changes to achieve the goals
  • Summary of pros and cons
  • Discarded solution spaces and why they were discarded
  • References
  • Changelog
Note the distinction between an ADR and a spec. The ADR provides the context, intuition, reasoning, and justification for a change in architecture, or for the architecture of something new. The spec is much more compressed and streamlined summary of everything as it stands today. If recorded decisions turn out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match.

​
Creating new ADR

Read about the PROCESS.

​
Use RFC 2119 Keywords

When writing ADRs, follow the same best practices for writing RFCs. When writing RFCs, key words are used to signify the requirements in the specification. These words are often capitalized: “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL. They are to be interpreted as described in RFC 2119.

​
ADR Table of Contents

​
Accepted

  • n/a

​
Proposed

​
Draft

  • n/a

​
Rejected

​
Deprecated