2014-04-17 2:11 GMT+02:00 Alex Crichton <[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. > > 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
