We should probably start using the #[deprecated] attribute more. Using it to phase things out in the std is currently annoying because we have the #[deny(deprecated)] attribute on.
~Brendan On 19 Feb 2014, at 12:40 pm, Brian Anderson <[email protected]> wrote: > Hey there. > > I'd like to start the long process of stabilizing the libraries, and this is > the opening salvo. This process and the tooling to support it has been > percolating on the issue tracker for a while, but this is a summary of how I > expect it to work. Assuming everybody feels good about it, we'll start trying > to make some simple API's stable starting later this week or next. > > > # What is the stability index and stability attributes? > > The stability index is a way of tracking, at the item level, which library > features are safe to use backwards-compatibly. The intent is that the checks > for stability catch all backwards-incompatible uses of library features. > Between feature gates and stability > > The stability index of any particular item can be manually applied with > stability attributes, like `#[unstable]`. > > These definitions are taken directly from the node.js documentation. node.js > additionally defines the 'locked' and 'frozen' levels, but I don't think we > need them yet. > > * Stability: 0 - Deprecated > > This feature is known to be problematic, and changes are > planned. Do not rely on it. Use of the feature may cause warnings. > Backwards > compatibility should not be expected. > > * Stability: 1 - Experimental > > This feature was introduced recently, and may change > or be removed in future versions. Please try it out and provide feedback. > If it addresses a use-case that is important to you, tell the node core > team. > > * Stability: 2 - Unstable > > The API is in the process of settling, but has not yet had > sufficient real-world testing to be considered stable. > Backwards-compatibility > will be maintained if reasonable. > > * Stability: 3 - Stable > > The API has proven satisfactory, but cleanup in the underlying > code may cause minor changes. Backwards-compatibility is guaranteed. > > Crucially, once something becomes 'stable' its interface can no longer change > outside of extenuating circumstances - reviewers will need to be vigilant > about this. > > All items may have a stability index: crates, modules, structs, enums, > typedefs, fns, traits, impls, extern blocks; > extern statics and fns, methods (of inherent impls only). > > Implementations of traits may have their own stability index, but their > methods have the same stability as the trait's. > > > # How is the stability index determined and checked? > > First, if the node has a stability attribute then it has that stability index. > > Second, the AST is traversed and stability index is propagated downward to > any indexable node that isn't explicitly tagged. > > Reexported items maintain the stability they had in their original location. > > By default all nodes are *stable* - library authors have to opt-in to > stability index tracking. This may end up being the wrong default and we'll > want to revisit. > > During compilation the stabilization lint does at least the following checks: > > * All components of all paths, in all syntactic positions are checked, > including in > * use statements > * trait implementation and inheritance > * type parameter bounds > * Casts to traits - checks the trait impl > * Method calls - checks the method stability > > Note that not all of this is implemented, and we won't have complete tool > support to start with. > > > # What's the process for promoting libraries to stable? > > For 1.0 we're mostly concerned with promoting large portions of std to > stable; most of the other libraries can be experimental or unstable. It's > going to be a lengthy process, and it's going to require some iteration to > figure out how it works best. > > The process 'leader' for a particular module will post a stabilization RFC to > the mailing list. Within, she will state the API's under discussion, offer an > overview of their functionality, the patterns used, related API's and the > patterns they use, and finally offer specific suggestions about how the API > needs to be improved or not before it's final. If she can confidently > recommend that some API's can be tagged stable as-is then that helps > everybody. > > After a week of discussion she will summarize the consensus, tag anything as > stable that already has agreement, file and nominate issues for the > remaining, and ensure that *somebody makes the changes*. > > During this process we don't necessarily need to arrive at a plan to > stabilize everything that comes up; we just need to get the most crucial > features stable, and make continual progress. > > We'll start by establishing a stability baseline, tagging most everything > experimental or unstable, then proceed to the very simplest modules, like > 'mem', 'ptr', 'cast', 'raw'. > > _______________________________________________ > 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
