OpenSSL NEWS.md 写作规范NEWS-FORMAT全解析从版本条目结构到发布流程的工程化实践【免费下载链接】opensslGeneral purpose TLS and crypto library项目地址: https://gitcode.com/GitHub_Trending/ope/openssl导读本文以 OpenSSL 仓库中面向维护者与贡献者的 dev/NEWS-FORMAT.md 规范文档为主体系统讲解 OpenSSL 自 3.2 起将NEWS.md打造为发布说明release notes的编辑约定包括 release line 的分区结构、单个发布条目的六类内容块模板、RFC/CVE/issue 的引用格式以及如何与 NEWS.md、CHANGES.md 和 dev/release-aux 下的发布辅助脚本协同工作。读完本文你将能够理解并审阅 OpenSSL 的 NEWS 条目是否符合官方规范、掌握各类内容块的措辞模板并了解发布流程中标题与日期是如何被自动化脚本改写的。背景从变更日志到发布说明NEWS.md在 OpenSSL 仓库中位于根目录其职责是给出每个 OpenSSL 版本之间主要变更的简要概览更详细的变更清单则由 CHANGES.md 承载CHANGES.md 开头明确写着For a high-level overview of changes in each release, see NEWS.md。两个文件互相引用、分工明确NEWS.md面向消费版本的广大用户CHANGES.md面向需要逐条追溯细节的开发者。从 OpenSSL 3.2 开始规范原文 With 3.2 onwards维护团队希望让NEWS.md更像真正的 release notes——按照对使用方有用的、结构化的方式组织信息而不再是一份松散的变更流水账。这一转变体现在本仓库实际生成的 NEWS 文件中以 NEWS.md 中 OpenSSL 4.0.2 条目为例它被组织为安全补丁说明security patch release 一组带 CVE 链接的修复列表而 3.2.0 条目则完整包含不兼容变更—新特性—已知问题—文档增强—缺陷修复—尾部建议全部结构块。这正是 NEWS-FORMAT 规范落地后的成品形态。通用编辑原则规范第一部分给出了一组适用于整个文件的编辑原则全部是推荐而非强制要求Everything here is a recommendation, not a requirement列表符号顶层列表统一使用*且每个列表项之间留一个空行。这样做的原因很务实——用户解压 tarball 后常常直接以纯文本形式阅读该文件空白行能显著提升裸读可读性。RFC 引用格式引用 RFC 时在编号前加空格写作RFC 9000而不是RFC9000。URL 集中管理URL 统一放在文件末尾并以引用方式reference link使用而不是内联书写。这样当某个被多处引用的公共 URL 需要变更时只需改一处便于维护。重要性降序一个 release line 分区内各内容块按重要性大致降序排列同一内容块内的列表项也按重要性或严重程度降序排列。与博客措辞对齐尽量让措辞与配套发布的博客文章一致尤其是新特性清单。措辞统一但不僵化适合的地方采用统一措辞但若统一措辞不可行或并非最优不必强求。省略空块没有任何条目可列的内容块应当整体省略。规范还特别提示块内列表项应使用完整句子并以句号结尾针对不兼容变更与缺陷修复而新特性列表项则是不带句号的摘要行因为该块的引导句已经提供了动词。上述原则都可以在当前 NEWS.md 中逐条验证例如 3.2.0 条目末尾的[CHANGES.md]、[README-QUIC.md]、[issue tracker]等引用链接全部集中在文件后部各块内部按最重要在前排列——4.0.2 条目中 CVEs 按严重程度从 Moderate 开始逐条列出。文件级结构release line 分区每个 release line如 3.2、3.5、4.0拥有一个独立分区分区内部先按版本倒序排列最近的版本在最前面最老最初特性发布在最后。规范给出了如下骨架OpenSSL x.y ----------- entry for patch releases of OpenSSL x.y... entry for patch releases of OpenSSL x.y... entry for initial (feature) release of OpenSSL x.y对照仓库中的 NEWS.md可以清晰看到 OpenSSL 3.2 分区内的实际排布先是 3.2.1/3.2.2 等补丁版本条目最后是 ### Major changes between OpenSSL 3.1 and OpenSSL 3.2.0 [23 Nov 2023] 这一特性发布条目。分区标题本身沿用文件开头的NEWS标题层级OpenSSL x.y作为二级标题条目用三级标题###。发布条目的标准结构对于每个发布规范推荐的结构模板为### Major changes between OpenSSL {PREV_VERSION} and OpenSSL {VERSION} [1 Jan 2023] opener paragraph one or more blocks listed below as applicable, in order shown below trailing advice标题中的日期放在方括号内如 NEWS.md 中的### Major changes between OpenSSL 3.6 and OpenSSL 4.0.0 [14 Apr 2026]。对于尚未定稿的开发中版本日期写为[under development]例如### Major changes between OpenSSL 4.0 and OpenSSL 4.1 [under development]。引导段Opener paragraph引导段根据发布类型有三种推荐措辞特性发布OpenSSL x.y.0 is a feature release adding significant new functionality to OpenSSL.见 4.0.0 与 3.2.0 条目原文无 CVE 的补丁发布OpenSSL x.y.z is a patch release.修复了 CVE 的补丁发布OpenSSL x.y.z is a security patch release. The most severe CVE fixed in this release is Medium.其中严重程度如 High、Moderate按实际情况调整。仓库实际示例中4.0.1 条目写的是 The most severe CVE fixed in this release is High.4.0.2 条目则写 The most severe CVE fixed in this release is Moderate.与模板一一对应。潜在不兼容变更块存在重大或破坏性变更时添加如下块This release incorporates the following potentially significant or incompatible changes: * The ... has been changed so that xxx. * The ... has been changed so that yyy.该块内列表项必须是带句号结尾的完整句子给出简要概括如需可另起完整段落补充细节。4.0.0 条目不兼容变更块就是最好的范例从 Removed support for SSLv3、Removed support for engines 到 ASN1_STRINGhas been made opaque共列举了二十余项每一项都是一句以句号结尾的完整陈述。新特性块有特性新增时添加如下块This release adds the following new features: * Support for ... (RFC 1234) * Support for ... (RFC 2345) This is an elaborating paragraph. * Multiple new features and improvements to ...该块列表项的规则与前者不同摘要行不带句号可在括号中附加适用的标准引用如RFC 9000可另起完整段落补充说明缩进对齐。摘要行不应以动词开头因为引导句 This release adds the following new features 已提供了动词为保持一致尽可能使用Support for ...作为摘要行措辞。特性按重要性大致降序排列。3.2.0 条目是该块的教科书级示范Support for client side QUIC, including support for multiple streams (RFC 9000)排在最前随后是Ed25519ctx/Ed25519ph/Ed448ph (RFC 8032)、deterministic ECDSA signatures (RFC 6979)、AES-GCM-SIV (RFC 8452)、Argon2 KDF (RFC 9106)、HPKE (RFC 9180)等并附带provider-based 可插拔签名算法使后量子密码成为可能这样的展开段落。已知问题块已知问题按如下方式列出The following known issues are present in this release and will be rectified in a future release: * xxx (#12345)该块编辑约定与特性块类似区别在于列表项中列出的是issue 编号而非标准引用。仓库实际案例可见 3.2.0 条目Provider-based signature algorithms cannot be configured using the SignatureAlgorithms configuration file parameter (#22761)。文档增强块重要文档增强可按如下方式列出This release incorporates the following documentation enhancements: * Added xyz This is an elaborating paragraph, which might for example provide a link to where this documentation can be viewed. * Clarified xyz该块与特性块约定类似但动词属于摘要行本身Added .../Clarified ...为推荐措辞。3.2.0 条目中的文档增强块即写为 Added multiple tutorials on the OpenSSL library ... See [OpenSSL Guide]。缺陷修复与缓解块重要缺陷修复或缓解措施按如下方式列出This release incorporates the following bug fixes and mitigations: * Mitigated description of mitigation (CVE ID as link and any other relevant links) * Fixed description of fix (optional reference link or #issue number as appropriate)引导句中的 bug fixes 或 mitigations 若与发布实际情况不符应删去对应词。主仓库内带编号的 issue 写作#1234其他来源的 issue例如第三方项目必须给出链接因为多数用户不知道去哪里查。排序规则CVE 缓解项在前、按严重程度降序随后是 bug按大致的严重程度降序。4.0.2 条目完美体现了这一规则11 条 Fixed ... 全部以 CVE 链接形式出现4.0.1 条目更是连列 18 条 CVE 修复。尾部建议Trailing advice规范推荐以下文末模板A more detailed list of changes in this release can be found in the [CHANGES.md] file. As always, bug reports and issues relating to OpenSSL can be [filed on our issue tracker][issue tracker].若某特性还附带专门文档可在尾部追加指向该文档的引用链接。3.2.0 条目即在此基础上追加了 Users interested in using the new QUIC functionality are encouraged to read the [README file for QUIC][README-QUIC.md]。发布自动化标题与日期的机器改写NEWS-FORMAT 规范描述的是人写作时应遵循的约定而 dev/release-aux 目录下的 Perl 脚本则展示了这些约定在发布流程中如何被机器强制执行——这正是规范与工程实践的衔接点。dev/release-aux/fixup-NEWS.md-release.pl作为perl -p过滤器运行只处理文件中的第一条### Major changes between OpenSSL ... [under development]行利用环境变量RELEASE_TEXT、RELEASE_DATE将其改写为带正式版本号与日期的标题若版本号形如x.y.z-alpha/beta日期则写为in pre-release。dev/release-aux/fixup-NEWS.md-postrelease.pl在发布完成后运行同样只处理第一条[under development]标题。它会把刚发布的版本条目日期固定为PREV_RELEASE_DATE并在其上方插入一个新的[under development]条目占位含一行* none同时用RELEASE_TEXT替换上一条发布对应的前一版本号——从而无缝开启下一个开发周期。这两条脚本与规范中的标题模板### Major changes between OpenSSL {PREV_VERSION} and OpenSSL {VERSION} [date]严格对齐说明 NEWS 标题的格式约定不仅是文风偏好更是发布流水线的解析契约。同样地dev/release-aux 中还提供 fixup-CHANGES.md-release.pl 与 fixup-CHANGES.md-postrelease.pl 对 CHANGES.md 做同步处理印证了NEWS 面向用户、CHANGES 面向开发者的双文件协作机制。实战自查清单结合规范与仓库现状向 OpenSSL 提交 NEWS 条目或审查他人条目时可按如下清单逐项核对标题格式### Major changes between OpenSSL {前一版本} and OpenSSL {本版本} [{日期}]未发布版本用[under development]。引导段特性发布 / 补丁发布 / 安全补丁发布三种措辞选一安全补丁需给出最高 CVE 严重程度。块顺序不兼容变更 → 新特性 → 已知问题 → 文档增强 → 缺陷修复与缓解 → 尾部建议空块省略。块内排序按重要性/严重程度降序CVE 修复排在最前issue 修复在后。措辞规则不兼容变更与修复用带句号的完整句子特性用不带句号的Support for ...摘要行动词交给引导句。引用格式RFC 写作RFC 9000带空格主仓库 issue 写作#1234CVE 与外部 issue 用链接。URL 位置所有 URL 集中在文件末尾做引用链接正文不内联。列表排版顶层列表用*列表项之间留空行保证 tarball 裸读体验。总结dev/NEWS-FORMAT.md虽只有两百余行却是 OpenSSL 发布工程的用户侧门面规范它定义了 NEWS.md 从文件级分区到单条目内容块的全套骨架与措辞约定与 NEWS.md 中的实际条目、CHANGES.md 的细节承载、以及 dev/release-aux 中自动改写标题日期的 Perl 脚本共同构成一套完整的 release notes 生产体系。理解这份规范既能让你快速读懂任何一条 OpenSSL 发布说明的结构与优先级信号也能为维护自研项目的 release notes 流程提供可直接借鉴的模板化思路——毕竟Everything here is a recommendation, not a requirement 这句话本身就为各种工程场景下的灵活套用留足了空间。【免费下载链接】opensslGeneral purpose TLS and crypto library项目地址: https://gitcode.com/GitHub_Trending/ope/openssl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考