docker_practice/appendix/example_guidelines.md

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

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

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)；且带有子标题的章节，在进入第一个子标题前，必须要有引导/过渡段落介绍该节内容。