免责声明:我是gitchangelog的作者,我将在下面进行介绍。
TL; DR:您可能想要检查gitchangelog自己的更改日志或生成前一个的ascii输出。
如果要从git历史记录生成变更日志,则可能必须考虑:
- 在输出格式。(纯自定义ASCII,Debian changelog类型,Markdow,ReST ...)
- 一些提交过滤(您可能不希望将所有错字或外观更改都包含在变更日志中)
- 一些提交文本在包含在变更日志中之前一直处于争执状态。(确保将消息标准化为具有首字母大写或最后一个点,但也可以删除摘要中的一些特殊标记)
- 您的git历史记录兼容吗?大多数工具并不总是那么容易地支持合并,标记。这取决于您如何管理历史记录。
可选地,您可能需要一些分类(新事物,更改,错误修正)...
考虑到所有这些,我创建并使用了gitchangelog。这意味着利用git commit消息约定来实现所有先前的目标。
必须使用提交消息约定来创建一个不错的变更日志(无论是否使用gitchangelog
)。
提交消息约定
以下是关于考虑添加提交消息可能有用的建议。
您可能希望将提交大致分为以下几部分:
- 按意图(例如:新,修复,更改...)
- 按对象(例如:doc,包装,代码...)
- 按受众群体(例如:开发人员,测试人员,用户...)
另外,您可能想标记一些提交:
- 因为“次要”提交不应输出到您的变更日志中(外观变更,注释中的小错字...)
- 如果您确实没有任何重大的功能更改,则将其作为“重构”。因此,例如,这也不应该是显示给最终用户的变更日志的一部分,但是如果您有开发人员变更日志,则可能会引起一些关注。
- 您也可以用“ api”标记以标记API更改或新的API内容...
- ...等等...
尝试通过尽可能地定位用户(功能)来编写提交消息。
例
这是git log --oneline
显示这些信息如何存储的标准方法:
* 5a39f73 fix: encoding issues with non-ascii chars.
* a60d77a new: pkg: added ``.travis.yml`` for automated tests.
* 57129ba new: much greater performance on big repository by issuing only one shell command for all the commits. (fixes #7)
* 6b4b267 chg: dev: refactored out the formatting characters from GIT.
* 197b069 new: dev: reverse ``natural`` order to get reverse chronological order by default. !refactor
* 6b891bc new: add utf-8 encoding declaration !minor
因此,如果您已经注意到,我选择的格式是:
{new|chg|fix}: [{dev|pkg}:] COMMIT_MESSAGE [!{minor|refactor} ... ]
要查看实际的输出结果,您可以查看gitchangelog的PyPI页面的末尾
要查看我的提交消息约定的完整文档,可以查看参考文件gitchangelog.rc.reference
如何从中生成精美的变更日志
然后,很容易制作完整的变更日志。您可以相当快地制作自己的脚本,也可以使用gitchangelog
。
gitchangelog
将会生成完整的变更日志(支持分段显示为New
,Fix
...),并且可以合理地配置为自己的提交约定。由于使用temp Mustache
,它支持任何类型的输出Mako templating
,并且具有以原始python编写的默认旧式引擎;当前所有3个引擎都有如何使用它们的示例,并且可以输出changelog的内容作为gitchangelog的PyPI页面上显示的内容。
我敢肯定,你知道,有很多其他的git log
到changelog
工具,在那里也。
--graph
,该标记可以直观地显示提交所在的分支。