Feature Request

Summary

When an API in a Rust program was changed (edited, added, removed) we should automatically document that under a new header called ## API.

Motivation

One of the most important things in a program to keep tabs on between versions are API changes. It'd be fantastic if we could automatically document which APIs were added, removed or changed so that upgrading between versions will become easier.

Behavior Level Guide

1. When changelog is run, it computes a changelog for the last version based on git/github information.
2. In addition, it detects whether a Cargo.toml file is present, and computes & documents the API changes.

Implementation Level Guide

The best place to start is probably rust-semverver, because it's already capable of generating API changelogs. We'd need to find a way to consume it as a library, and output it as markdown -- but my guess is that for a prototype that should be relatively straightforward.

Maybe we should also raise an issue there stating our intents, to see if we can collaborate on making this feature happen.

Drawbacks

People might attach too much value to API changes, and forget to consider changes in side effects as relevant to semver. This method will only be able to prove changes occurred, but not that everything is consistent. Therefor we should not attach too much value to it.

Rationale and alternatives

Without this feature, people need to manually compare versions to figure out what changed. This is relatively labor intensive, and must be repeated for every person upgrading. By documenting the API changes, we can pre-compute an overview of changes which makes upgrading easier.

Unresolved Questions

• This issue does not address how to document CLI API changes.
• Neither does it address how to document ABI changes.
• Nor does it address non-rust projects.