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