# 附录八：本书示例规范与写作公约

为了保证本书在漫长的技术迭代中保持高质量、高安全性以及良好的可读性，我们确立了以下项目写作规范。所有的修改与贡献都必须遵循这些原则。

## 1. 安全与凭据处理

任何示例文档中都 **严禁出现将凭据以明文形式直接传递给命令参数** 的做法。

* **错误示例**：`docker login -u myuser -p mysecretpassword` (这会导致密码泄露到历史记录及进程列表中)
* **正确示例（交互式）**：推荐读者直接使用 `docker login` (优先使用官方 Device Code Flow)。
* **正确示例（自动化）**：使用标准输入流传递 Token：`echo $PAT | docker login -u myuser --password-stdin`

## 2. 失败模式与前置条件说明

许多现代 Docker 功能 (如 Buildx, SBOM, Kubernetes CRI 集成) 均需要特定的后端存储或者组件支持。在介绍这些进阶命令时，必须：

* **明确声明前置条件**：例如，“此功能需要开启 containerd image store” 或 “需要额外配置 `--push`”。
* **描述失败现象**：明确告诉读者，“如果你不这么配置，命令仍会提示成功，但产物将不可见/被丢弃”。

## 3. 统一使用 “docker compose” 命令

早期 Python 编写的 `docker-compose` (V1) 已停止支持。

* **全书统一标准**：所有的编排命令必须书写为 `docker compose` (带空格的 V2 CLI 插件版)。
* 不得在新的文档和案例中提及或使用旧版格式，除非是为了特意说明 V1 到 V2 的迁移。

## 4. 可复现性目标 (以可重建为目标)

本书中的所有实战和案例 (尤其 OS 与 DevOps 章节) 应尽量给出“最小可复现实验环境”。

* 提供明确的基础镜像版本要求 (不要盲目依赖 `latest`)。
* 明确宿主机的生命周期窗口（例如明确注出 Ubuntu 20.04 的支持结束时间）。

## 5. Markdown 格式纪律

我们使用自动化的格式检查工具 (`check_project_rules.py`) 进行 Lint。以下是必须遵守的排版底线：

* **加粗与空格**：加粗符号内不得有空格（`**错误 黑体**` ❌， `**正确黑体**` ✅）。
* **标题间距**：标题后必须跟恰好一个空行。
* **中文标点**：正文叙述部分的引号必须使用中文弯引号 `“”`，不得使用英文直引号 `""`（除了代码块或 Mermaid 图表中）。
* **层级与桥接**：禁止跳跃级别使用标题 (如 H2 后直接接 H4)；且带有子标题的章节，在进入第一个子标题前，必须要有引导/过渡段落介绍该节内容。