mirror of
https://github.com/yeasy/docker_practice.git
synced 2026-03-11 12:21:17 +00:00
42 lines
2.6 KiB
Go
42 lines
2.6 KiB
Go
# 附录八：本书示例规范与写作公约
|
||
|
||
为了保证本书在漫长的技术迭代中保持高质量、高安全性以及良好的可读性，我们确立了以下项目写作规范。所有的修改与贡献都必须遵循这些原则。
|
||
|
||
## 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)；且带有子标题的章节，在进入第一个子标题前，必须要有引导/过渡段落介绍该节内容。
|