在不破坏公共API的前提下，对底层库做小范围修改

## 改动保持最小，未经要求不改公共API和ABI 将稳定的公共应用程序编程接口和应用二进制接口视为硬性约束。 ### 编辑前 - 进行非简单工作前，阅读仓库的构建、测试、配置、贡献和发布文档。 - 确定负责所请求变更的单一子系统或事项。 - 遵循每个所改文件的局部惯例。 - 保留无关的用户变更和未跟踪产物。 ### 变更边界 - 优先采用最小差异和渐进式后续变更，而不是大范围重写。 - 不要重命名、重新排序、重新格式化或清理无关代码。 - 除非明确要求，否则不要添加新的公共接口。 - 除非明确要求，否则不要更改或移除现有公共接口或二进制契约。 - 保留可选功能行为、精简功能构建和编译时功能防护。 - 不要暗中更改构建或功能的默认值。 当看似别扭的代码位于兼容性边界时，在测试、历史和周边行为证明并非如此之前，应假定它可能处理真实的边界情况。 ## 按标准流程构建，并运行改动子系统的测试 在依赖专项检查之前，先使用仓库的标准配置、编译和测试流程。 ### 默认流程 1. 配置或重新配置指定的构建目录。 2. 编译受影响的目标。 3. 运行适合当前阶段的测试套件。 4. 确认构建没有引入新的警告。 如果构建目录尚不存在，应进行初始配置，而不是只走重新配置路径。每次对代码作出实质性更改后，都要重新构建所改目标。 ### 最低限度的专项检查 - 对于转换或文本整形逻辑，运行其专用行为测试套件。 - 对于缩减、子集化或图结构相关工作，运行相应的子系统测试套件。 - 对于公共接口工作，运行应用程序编程接口测试套件。 - 对于命令行工具工作，重新构建相关工具，并用一个小型代表性样本实际运行。 - 对于错误修复或解析器加固，在可行时添加或更新最接近的回归测试、模糊测试输入、模糊测试目标或预期结果。 专项检查可以加快迭代，但当共享行为或发布准备状态受到影响时，它们不能取代更广泛的验证。 ## 按子系统选择修改位置，并沿用项目已有的写法 在选择修改代码的位置之前，先理解相邻职责。 ### 职责边界 - 将核心库行为与已安装工具、性能基准、文档、语言绑定和实验性组件分开。 - 当图结构辅助逻辑参与缩减流程的行为时，将其视为该流程的一部分。 - 对于栅格、矢量、图形或类似的过大编译单元，优先提取职责明确的辅助逻辑并按职责拆分，而不是增加更多分支。 - 对于语言集成，在更改构建衔接逻辑前，同时检查原生构建定义和语言包清单。 ### 现有惯例 - 使用项目既有的内存分配、错误处理、分支预测、空对象、容器和实用工具模式。 - 当项目封装包含可移植性或安全行为时，优先使用项目封装，而不是原始的平台基础操作。 - 当项目已有成熟的容器和实用工具时，不要把外部容器库引入核心代码。 - 将公共接口文档添加到仓库惯用的源码或文档位置。 当重复的解析、缓存或辅助逻辑开始扩散时，应将其集中起来，但不要把一项范围有限的修复变成无关的架构重写。 ## 在所有支持的平台上，遇到内存错误或恶意输入时安全失败 将分配失败、恶意输入、编译器多样性和精简功能构建视为受支持范围的正常组成部分。 ### 分配与解析器安全 - 遵循现有的分配和错误处理模式，使新代码在内存压力下安全失败。 - 在加固输入处理之前，检查现有的解析器防护和模糊测试基础设施。 - 注入分配失败时，最低可接受结果是没有崩溃、越界访问或内存损坏。 - 对于实验性组件，在内存压力下尽力尽早失败是可以接受的。 - 除非组件契约要求，否则不要仅为保留分配失败后的部分工作而添加复杂的回滚逻辑。 ### 可移植性 - 将编译器、操作系统、架构位宽、交叉构建和精简功能构建的回归视为真实错误。 - 在项目支持的工具链和整数位宽范围内验证假设。 - 持续实际运行编译时功能防护和回退路径。 - 简化底层代码时，检查原有复杂性是否用于处理对齐、溢出、生命周期、别名规则或平台特定行为。 优先提供可复现的回归，而不是只能修复问题却无法证明原始故障的变更。 ## 不手改生成的表，而是用生成器重新生成 使每一份构建描述和生成结果都与源码变更保持同步。 ### 构建系统变更 - 同步更新选项、配置摘要、已安装工具、测试和依赖目标。 - 如果影响打包或交叉构建，应检查所有受支持的构建系统，而不是只更改主要构建系统。 - 除非任务明确要求更改默认值，否则保留选项的默认值。 - 对受影响的可选功能，同时验证启用和禁用两种形式。 ### 生成数据 - 修改生成器、源数据或构建自动化流程，然后重新生成结果。 - 除非任务明确要求，否则不要手动编辑生成的表或索引。 - 不要假定生成结果、本地测试资源、字体或未跟踪产物可以丢弃。 - 检查重新生成的差异是否出现意外扩散或非确定性变更。 如果生成器变更影响公共数据或测试预期，应在同一项范围有限的变更中更新相关测试和文档。 ## 只在被要求时添加公共API，并附上版本标记和文档 将用户可见行为作为代码、文档、版本管理和构建衔接相互协调的变更来处理。 ### 公共接口关卡 - 将公共声明放在指定的公共头文件或模块中，而不是内部实现文件中。 - 只有请求明确授权时，才能添加新的公共接口。 - 新接口获得授权后，添加仓库要求的版本标记和发布说明条目。 - 通过批准的流程更新生成的章节索引、文档清单或参考列表。 - 除非明确批准破坏兼容性的变更，否则保留二进制布局、符号可见性、调用约定和源码兼容性。 ### 用户可见行为 - 当功能通过库或已安装工具对用户可见时，更新相关文档。 - 使安装和构建衔接与新公开的行为保持同步。 - 按照局部惯例，将公共接口文档和生成索引放在规定位置。 - 不要仅为让测试成功而禁用失败的测试；应记录合理的例外及其影响。 ## 先查清根本原因，提交但不推送 在把变更表述为完成之前，证明原因和结果。 ### 工作方法 1. 在可行时复现问题。 2. 在编写修复前理解根本原因。 3. 如果仍存在实质性歧义，应提问而不是猜测。 4. 在简化看似异常复杂的代码前检查历史。 5. 添加或更新最接近的回归覆盖。 6. 验证所改子系统、受影响配置和更广泛的行为。 ### 提交规范 - 在提交代码、构建逻辑、生成结果或测试输入之前，运行完整测试套件。 - 仅涉及文档或持续集成的变更，只有在不可能影响上述领域时才能跳过完整测试；应报告该省略。 - 每次提交只集中处理一个问题或事项。 - 绝不要推送到远程仓库；将推送交给获得授权的人。 - 使用仓库规定的子系统前缀、署名尾注和信息惯例。 - 对于多行提交信息，使用文件或由编辑器提供的输入，而不是带转义符的换行序列。 - 只有实际完成的工作能够提供依据时，才描述根本原因、修复和测试。 交接时，报告变更范围、已运行的测试、警告、不受支持的配置、未解决的风险以及任何未执行的验证。