On 04/17/2014 12:21 AM, Flaper87 wrote:
2014-04-17 2:11 GMT+02:00 Alex Crichton <[email protected]
<mailto:[email protected]>>:
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]
Sometimes, the breaking change is split in several commits. I'd
recommend to add to the breaking change tag the number of the GH issue
(I wanted to propose a "change tag" but I don't think that will end
well). I don't expect breaking changes to happen without a GH issue
baking them - or at least, I don't think that should happen.
Tagging the last commit of the series should probably be enough but, for
completeness, I think they should all be tagged. This will produce a
more complete output when `grepping` for breaking changes.
I hope it's not typically hard to isolate the "break" to a single
commit, particularly when it comes to library refactoring, which is
where most of the breakage is going to be going forward.
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.
I think we should retain the previous functionality. Since it's already
there, I don't think it will be of any harm (in most of the cases).
Also, I think it'd be good to keep the deprecated function for at least
1 release. I believe this is a good practice and gives users of that
function enough time to migrate. This obviously doesn't make much sense
if we replace the functionality with a `fail`
# 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!
I'm really happy to see this happening!
--
Flavio (@flaper87) Percoco
http://www.flaper87.com
http://github.com/FlaPer87
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
_______________________________________________
Rust-dev mailing list
[email protected]
https://mail.mozilla.org/listinfo/rust-dev
