From b82e0ec031fa32f8af0dbfedcb17179cff89c406 Mon Sep 17 00:00:00 2001 From: yeasy Date: Wed, 18 Mar 2026 19:43:41 -0700 Subject: [PATCH] Remove appendix writing rules --- appendix/README.md | 1 - appendix/example_guidelines.md | 41 ---------------------------------- 2 files changed, 42 deletions(-) delete mode 100644 appendix/example_guidelines.md diff --git a/appendix/README.md b/appendix/README.md index 4b13b85..a0c0fce 100644 --- a/appendix/README.md +++ b/appendix/README.md @@ -11,4 +11,3 @@ * [**如何调试 Docker**](debug.md)：介绍 Docker 调试技巧和工具。 * [**资源链接**](resources.md)：推荐更多 Docker 相关的学习资源。 * [**术语词表**](glossary.md)：统一全书中英文术语、缩写与命令写法。 -* [**示例规范与写作公约**](example_guidelines.md)：全书修改与贡献必须遵守的安全、格式及内容基线要求。 diff --git a/appendix/example_guidelines.md b/appendix/example_guidelines.md deleted file mode 100644 index 93a0530..0000000 --- a/appendix/example_guidelines.md +++ /dev/null @@ -1,41 +0,0 @@ -# 附录八：本书示例规范与写作公约 - -为了保证本书在漫长的技术迭代中保持高质量、高安全性以及良好的可读性，我们确立了以下项目写作规范。所有的修改与贡献都必须遵循这些原则。 - -## 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)；且带有子标题的章节，在进入第一个子标题前，必须要有引导/过渡段落介绍该节内容。