79 lines
4.2 KiB
Markdown
79 lines
4.2 KiB
Markdown
# 文档体例与改写约定（全项目）
|
||
|
||
**范围**：本仓库**自有**说明文字——**`README.md`**、**`docs/`**、**`audio_topology/`**、**`patches/**/README*.md`**、根目录 **`next.md`**、**`REPO_INDEX.md`**、**`help.md`** 等。
|
||
**不包含**：**`_bmad/`**（BMad 安装树）、**`.cursor/`** 技能包、**`kernel-src/`**/**`chromiumos_kernel/`** 内上游源码（除非本仓库另有 `README` 说明）。
|
||
|
||
**目的**：统一口吻、入口与术语，便于本人、代理与换机交接阅读；与 **[DOCUMENTATION_ARCHITECTURE.md](./DOCUMENTATION_ARCHITECTURE.md)**（结构）互补——**本文管「怎么写」**，架构文管「往哪放」。
|
||
|
||
---
|
||
|
||
## 1. 语言与语气
|
||
|
||
| 项 | 约定 |
|
||
|----|------|
|
||
| **默认** | **简体中文**（与 `_bmad/bmm/config.yaml` 中 `document_output_language` 一致）。 |
|
||
| **技术专名** | 保留英文：`SOF`、`iDisp`、`PIPEWIRE`、`plughw`、`STREAM_PCM_PARAMS`、`dynamic_debug`、内核符号与路径。 |
|
||
| **句式** | 说明体：先**可执行结论**或**指向**，再背景；避免口号式空话。 |
|
||
| **版本与事实** | 写内核版本、`uname`、deb 后缀时**写全**或指到 `WORK_PROGRESS`/操作记录，避免半句过时数字。 |
|
||
|
||
---
|
||
|
||
## 2. 入口与互链（硬约定）
|
||
|
||
| 规则 | 说明 |
|
||
|------|------|
|
||
| **唯一根 README** | 仅 **[README.md](../../README.md)**；不在子目录另立「第二 README」抢入口。 |
|
||
| **主题索引** | 新增/改名主题文档后，在 **[docs/INDEX.md](../INDEX.md)** 增加或更新**一行**链入；全路径速查维护 **[REPO_INDEX.md](../../REPO_INDEX.md)**。 |
|
||
| **占位文件** | `docs/WORK_PROGRESS.md`、`docs/Linux_HDMI_Audio_Roadmap.md` 仅作**重定向**，正文以 **`meta/`**、**`linux-hdmi/`** 为准。 |
|
||
| **BMad** | **`docs/index.md`**（小写）与 **`INDEX.md`** 并存；代理规则 **`_bmad-output/project-context.md`**；勿合并二者。 |
|
||
| **NFR4 同事务** | 新增或移动主题文档、或改变 **`docs/` 导航结构**时，在**同一变更集**（或**紧随**的提交）中更新 **`docs/INDEX.md`** 与/或 **`REPO_INDEX.md`**；见 §6。 |
|
||
|
||
---
|
||
|
||
## 3. 文件命名（建议）
|
||
|
||
| 模式 | 用途 |
|
||
|------|------|
|
||
| **`OPERATION_*.md`** | 可重复执行的操作步骤（安装、trace、采集）。 |
|
||
| **`FIX_PLAN_*.md`** / **`REPAIR_Plan_*.md`** | 分阶段修复策略或跨平台总方案。 |
|
||
| **`*_Roadmap.md`** | 路线图、成功标准、已排除项。 |
|
||
| **`PHASE_*` / `ANALYSIS_*`** | 阶段结论或对比分析。 |
|
||
|
||
---
|
||
|
||
## 4. 术语简表（Kaisa / 音频）
|
||
|
||
| 用语 | 含义 |
|
||
|------|------|
|
||
| **Kaisa** | Google Chromebox 10 代参考板名称。 |
|
||
| **Coreboot** | 替代原厂固件后的引导环境（本仓库问题前提之一）。 |
|
||
| **HWE 6.17** | Ubuntu 24.04 的 **linux-hwe-6.17** 内核线（文档与补丁默认对齐对象）。 |
|
||
| **ChromeOS 5.15 / ChromiumOS 5.15** | 对照用内核分支语境；**不等于** Ubuntu Mainline 5.15 包。 |
|
||
|
||
---
|
||
|
||
## 5. 进度类文档分工（勿混写）
|
||
|
||
| 文件 | 只写 |
|
||
|------|------|
|
||
| **`docs/meta/WORK_PROGRESS.md`** | 已验证事实、阶段结论、clone/版本命令。 |
|
||
| **`next.md`（根）** | **临时**下一步；**含重启时**须分 **重启前 / 重启后**。 |
|
||
| **路线图 / FIX_PLAN** | 目标、分支、不宜投入项；不写日常命令流水账。 |
|
||
|
||
---
|
||
|
||
## 6. 改写清单（全项目落地时自检）
|
||
|
||
- [ ] 新文档已出现在 **INDEX**（及需要的 **REPO_INDEX**）中；合并请求或提交说明中**点明**索引行变更（便于评审 NFR4）。
|
||
- [ ] **现象与「已排除项」扩表**：优先只维护 **[linux-hdmi/Linux_HDMI_Audio_Roadmap.md](../linux-hdmi/Linux_HDMI_Audio_Roadmap.md) §一、§二**；其它文用**互链**代替复制表格。
|
||
- [ ] 无与 **路线图 / WORK_PROGRESS** 矛盾的「唯一真相」表述。
|
||
- [ ] 链接为**相对路径**（仓库内），避免仅域名依赖。
|
||
- [ ] 大目录（`kernel-src` 等）仍遵守 **`.gitignore`**，文档只描述路径不承诺提交内容。
|
||
|
||
---
|
||
|
||
## 7. 与 Index Docs 的关系
|
||
|
||
- **`[ID]`** 产出的 **[LLM_INDEX.md](../LLM_INDEX.md)**：按文件**短描述**导航。
|
||
- 体例变更时：先改**本文**，再视需要更新 **LLM_INDEX** 一行摘要。
|