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
