Greetings Rustlers!
Projects such as cargo and Servo have recently expressed interest in having a
"breaking changes" changelog as part of the rust repository. It's often
difficult for those not closely tied to the compiler itself to keep up with all
the changes that are getting made. Additionally, I imagine that some sort of
changelog such as this would be quite useful to others!
With this in mind, we're going to introduce two new measures to help developers
port code to newer versions of Rust. The first is to produce a "breaking changes
log" of changes to the language and its libraries that may break existing
code, *along with instructions for porting*. The second is to use the
#[deprecated] attribute more aggressively to instruct the compiler to inform
users how to upgrade their code.
# A log of Breaking Changes
The way we've decided to go about doing this is to start being stricter about
the content of commit messages. Any commit which is a breaking change will be
required to adhere to a particular template. In doing this, we hope to avoid
merge conflicts on one literal changelog file, and we also hope to leverage what
git already gives us. Note that this requires isolating the breaking change to a
single commit instead of having extra changes leak into the commit. If multiple
distinct breaking changes are made, they will require separate commits.
The precise definition of a breaking change will likely be an evolving concept,
but there are a few classes of changes that definitely count:
* Changing the semantics of existing functionality in the standard libraries
* Removing functionality from the standard libraries
* Modifications to the language itself (parsing and semantics)
The template which breaking changes will be required to look like is:
First, a brief one-line summary of the change
Second, take as long as is necessary to explain exactly what the change is,
why it's being changed, what it can be replaced with (if applicable) and
general guidelines about dealing with the change.
In addition to a few paragraphs about the change itself, the literal string
"[breaking-change]" must appear at the end of the commit message in order
to indicate that it is a commit that has a breaking change. This will allow
filtering commits on this string to only take a look at breaking changes.
[breaking-change]
To get a log of breaking changes, you can use git-log:
git log --grep breaking-change
# Exclude bors merge commits
git log --grep breaking-change --no-merges
# Usage of #[deprecated]
In addition to a stricter policy around commit messages, we're going to start
encouraging more aggressive use of the #[deprecated] attribute to help
transitioning code. A good example of this recently is when the `shuffle_mut`
function was renamed to `shuffle`. The original function had an attribute that
looked like:
#[deprecated = "function renamed to `shuffle`"]
We aren't yet going to require that the old function retain its functionality,
it is acceptable to replace it with a fail!()-ing stub for now. The compilation
warning should be a good enough indicator about what needs to be changed.
The deprecated functions themselves aren't expected to stick around for all
eternity. By 1.0 we will clean out all #[deprecated] functionality, and before
then we'll likely leave in #[deprecated] functions for about a month or so.
# Be on the lookout!
With these two guidelines in place, we hope to ease the pain of upgrading
through versions of rust while it's still under rapid development. Reviewers, be
sure to keep an eye out for breaking changes in the future and make sure that
the that these measures are followed!
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
