I’ve been coding Rust during my free time for a few months now (mostly on the spaceapi server, the telegram groups bot and rpsrtsrs). Something I noticed lately is that very rarely projects keep a changelog or provide release notes.
我已经在空闲时间编码Rust了几个月（主要是在spaceapi服务器 ， 电报组bot和rpsrtsrs上 ）。 我最近注意到的是，很少有项目保留更改日志或提供发行说明。
这种看法是真的吗？ (Is that perception true?)
Here is the list of the 10 most downloaded crates on crates.io (as of December 2015), and whether or not they provide a changelog in their code repository or in their README:
以下是crates.io （截至2015年12月）上下载次数最多的10个板条箱的列表，以及它们是否在其代码存储库或自述文件中提供更改日志：
| Crate | 箱 | Changelog | 变更日志 |
|---|---|---|---|
| libc | 图书馆 | ✗ | ✗ |
| winapi | Winapi | ✗ | ✗ |
| rustc-serialize | rustc序列化 | ✗ | ✗ |
| rand | 兰德 | ✗ | ✗ |
| log | 日志 | ✗ | ✗ |
| bitflags | 位标志 | ✗ | ✗ |
| winapi-build | Winapi的构建 | ✗ | ✗ |
| gcc | 海湾合作委员会 | ✗ | ✗ |
| time | 时间 | ✗ | ✗ |
| advapi32-sys | advapi32-sys | ✗ | ✗ |
Now most of these projects are “official” crates by the Rust project developers. Maybe these are somehow different? So as another comparison, let’s list some of the recent “notable crates” from the This Week In Rust newsletter, as well as some other random crates I frequently use:
现在，这些项目大多数是Rust项目开发人员的“官方”板条箱。 也许这些有所不同？ 因此，作为另一个比较，让我们列出“ This Week in Rust”时事通讯中的一些最近的“著名板条箱”，以及我经常使用的其他一些随机板条箱：
| Crate | 箱 | Changelog | 变更日志 |
|---|---|---|---|
| piston | 活塞 | ✗ | ✗ |
| glium | 胶质 | ✓ | ✓ |
| httparse | httparse | ✗ | ✗ |
| leaf | 叶 | ✗ | ✗ |
| nom | 标称 | ✓ | ✓ |
| barcoders | 条形码 | ✗ | ✗ |
| diesel | 柴油机 | ✓ | ✓ |
| chomp | 排骨 | ✗ | ✗ |
| hyper | 超 | ✓ | ✓ |
| iron | 铁 | ✗ | ✗ |
| rust-postgres | 锈-postgres | ✗ | ✗ |
| redis-rs | 重做 | ✗ | ✗ |
| r2d2 | 2天 | ✗ | ✗ |
The result is still sobering. Almost no Rust projects provide a changelog.
结果仍然很清醒。 几乎没有Rust项目提供变更日志。
什么是变更日志？ (What is a changelog?)
According to Wikipedia:
根据维基百科：
A changelog is a log or record of all the changes made to a project, such as a website or software project, usually including such records as bug fixes, new features, etc. Some open source projects include a changelog as one of the top level files in their distribution.
变更日志是对项目（例如网站或软件项目）所做的所有更改的日志或记录，通常包括诸如错误修复，新功能等记录。某些开源项目将变更日志列为最高级别之一文件在其分发中。
A changelog is usually kept in a file called ChangeLog, CHANGELOG.md, CHANGES.md or HISTORY.txt. The format varies. But the essence is: It keeps the users of the codebase up to date regarding the changes between different releases.
变更日志通常保存在名为ChangeLog ， CHANGELOG.md ， CHANGES.md或HISTORY.txt的文件中 。 格式各不相同。 但是本质是：它使代码库的用户可以随时了解有关不同版本之间的更改的最新信息。
但是我们有SemVer！ (But we have SemVer!)
By default, Cargo uses Semantic Versioning for resolving dependencies and their available versions. That’s a fantastic thing. SemVer provides a simple way to check whether a version update contains breaking changes or not, without having to look at any release notes or changelogs. This is definitely something I’m really happy about.
默认情况下，Cargo 使用 语义版本控制来解决依赖关系及其可用版本。 真是太好了。 SemVer提供了一种简单的方法来检查版本更新是否包含重大更改，而无需查看任何发行说明或变更日志。 这绝对是我真的很高兴的事情。
But the versioning scheme only helps with knowing that something breaks, but not what breaks. The first thing you should do whenever a crate that you depend on upgrades the major version, is to head to the project changelog to see whether you need to take any action regarding incompatibilities or deprecations.
但是，版本控制方案仅有助于了解某些问题，而不能了解哪些问题。 每当您依赖的板条箱升级主要版本时，您应该做的第一件事就是前往项目变更日志，以查看是否需要对不兼容或不赞成使用的措施。
Incompatible changes are a small detail when using binary projects, but not when dealing with libraries. Libraries are meant to be used directly and indirectly by other people. Changing code in a way that is reverse incompatible will break people’s code. So please let them know what changed and what they need to do about it.
使用二进制项目时，不兼容的更改很小，但在处理库时则不是。 图书馆应被其他人直接或间接使用。 以反向不兼容的方式更改代码会破坏人们的代码。 因此，请让他们知道发生了什么变化以及他们需要做什么。
但是我们有Git日志！ (But we have the Git log!)
The git log is not meant for a quick overview regarding important changes. It contains a lot of noise that isn’t relevant to your library users. As an outsider, it’s hard to learn about important changes from the git log. It is definitely no replacement for a proper changelog.
git日志无意对重要更改进行快速概述。 它包含许多与您的图书馆用户无关的噪音。 作为局外人，很难从git日志中了解重要的更改。 绝对不能替代适当的变更日志。
推荐建议 (Recommendations)
Here are a few recommendations regarding release and change management of libraries:
以下是有关库的发行和变更管理的一些建议：
- If you have a project on crates.io that doesn’t yet have a changelog, please add one, in a file called CHANGELOG.md.
- In the changelog, explicitly state that you follow semantic versioning (if you do, and you should).
- Write your changelog in an easy to read format. You can find one possible format here, or another one here.
- Every time you release a new version, tag the corresponding commit in your git repository with git tag vX.Y.Z. Don’t forget to push the tags upstream with git push --tags!
- 如果您在crates.io上有一个尚无变更日志的项目，请在一个名为CHANGELOG.md的文件中添加一个。
- 在变更日志中，明确声明您遵循语义版本控制（如果这样做，应该这样做）。
- 以易于阅读的格式编写您的变更日志。 你可以找到一个可能的格式在这里 ，或另外一个在这里 。
- 每次发布新版本时，请使用git tag vX.YZ在git存储库中标记相应的提交。 不要忘记使用git push --tags将标签推入上游 ！
You’ll find more details about why and how to keep changelogs on http://keepachangelog.com/.
您可以在http://keepachangelog.com/上找到有关为什么以及如何保留更改日志的更多详细信息。
进一步建议 (Further Recommendations)
Right now there’s no way to specify the changelog in your Cargo.toml. That’s a pity. So if there are any Cargo developers around: Please add an option to specify the changelog link in Cargo.toml and display the link on crates.io below the links to the repository and the documentation!
现在无法在Cargo.toml中指定更改日志。 真可惜。 因此，如果有任何货物开发商围：请添加选项来指定在Cargo.toml更改日志链接并显示链接crates.io以下链接库和文档！
Discuss on HackerNews and Reddit.
关于HackerNews和Reddit的讨论。
翻译自: https://www.pybloggers.com/2015/11/rustaceans-please-keep-a-changelog/
529
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
