setuptools-changelog 1.0.0

需求

• Python 2.7, 3.5+;

• setuptools (31+, 但最新版本更好)；

• 您的项目遵循语义版本控制或使用其简化的（X.Y版本）形式；

用法

0. 将setuptools-changelog作为开发依赖项添加到您的项目中；

1. 在项目根目录中创建changelog.d目录（setup.py所在位置）

2. 根据您所做的更改在此处创建片段文件。片段文件具有以下格式

   {name}.{type}.{ext}

   其中

   • name：片段名称。如果它以数字开头并且指定了问题跟踪器，则该数字将自动转换为问题引用。否则，可以是某些助记名称以简化导航。

   • type：片段类型。默认情况下，以下类型可用

     • 主要更改

       • epic：彻底改变底层项目平台的巨大史诗级更改。这可能涉及完全转向全新的基础库、框架等。史诗级更改非常罕见，是主要原因之一。

       • 破坏性变更：破坏性变更指的是项目中 公共API 的更改，这会导致旧代码与它们不兼容。不兼容意味着某些功能被移除或行为发生了改变。

     • 小改动

       • 安全：这是一个重要的安全修复。用户必须尽快更新。如果安全修复导致破坏性变更，应发布两个单独的变更日志片段。

       • 弃用：弃用是对公共API即将发生的破坏性变更的友好警告。

       • 新功能：新功能为项目带来了一些新东西，并且必须通过公共API对用户可用。

     • 补丁更改

       • 错误：当某件事情以它不应或未预期的方式工作时，我们进行错误修复。

       • 改进：这可能包括速度优化、内部重构、使代码更稳定等。改进永远不会改变现有的行为或公共API。

       • 构建：与项目构建流程、打包等相关更改。

       • 文档：文档更新、说明、拼写错误修复等。

       • 测试：围绕项目测试、测试套件、CI等进行的工作。

       • 杂项：不适合任何现有类别的杂项更改。例如，它们可能是关于项目生命的公告：新提交者、认可等。

   • 扩展名：文件扩展名。目前，我们只支持 rst 一种。

3. 您可以通过以下方式预览变更日志

   python setup.py changelog

4. 一旦您准备好发布，您可以更新您的变更日志文件如下

   python setup.py changelog --update=CHANGELOG.rst

   此命令将 添加 生成的变更日志到您的文件中。

5. 审查您的变更日志文件内容，确认无误后提交并删除片段

   git rm changelog.d/*
   git commit CHANGELOG.rst changelog.d/

使用默认值的 setup.cfg 示例配置

[changelog]
changelog_fragments_path = changelog.d
major_changes_types =
    epic = Epic Changes
    breaking = Breaking Changes
    removal = Breaking Changes
minor_changes_types =
    security = Security Fixes
    deprecation = Deprecations
    feature = New Features
patch_changes_types =
    bug = Bug Fixes
    bugfix = Bug Fixes
    improvement = Improvements
    build = Build
    doc = Documentation
    test = Tests Suite
    misc = Miscellaneous

自动版本生成

如果您的项目遵循 语义化版本控制 策略，您不仅可以实现变更日志生成，还可以根据变更自动进行版本管理。

与 towncrier 的集成

这个项目开始的原因有几个，让我不想使用 towncrier 来管理变更日志。但是

为什么不拥有敌人，当你可以拥有朋友时？

——亚瑟王：剑之传奇

相反，我们可以通过以下配置支持为 towncrier 制作的片段

[changelog]
changelog_fragments_path = changelog.d
major_changes_types =
    removal = Breaking Changes
minor_changes_types =
    feature = New Features
patch_changes_types =
    bugfix = Bug Fixes
    doc = Documentation
    misc = Miscellaneous
use_towncrier = true

就是这样！