stabilization template, docs #2219

nikomatsakis · 2025-01-23T20:24:58Z

This PR updates the stabilization docs and introduces a new stabilization template based on a series of questions.

cc @rust-lang/lang -- this is designed to help us get the information we need
cc @rust-lang/compiler -- this is designed to ask questions to help gauge implementation quality
cc @rust-lang/types -- this is designed to surface potential type system interactons
cc @rust-lang/style, @rust-lang/rust-analyzer, and @rust-lang/lang-docs -- I'd like advice on how to advice users about doing updates outside of rustc.

jackh726

I love this.

src/implementing_new_features.md

jackh726 · 2025-01-23T20:52:25Z

src/implementing_new_features.md

+
+## Affiliated work
+
+Once the feature is supported by rustc, there is other associated work that needs to be done to give users a complete experience:


Would be good to note on current expectations on if this work is blocking (and to what extent)?

Well, this in regards to stabilization, but I do think this comment fits here (i.e. maybe the guideline is "you shouldn't try to stabilize if the affiliated work is not completed")

I think it would, to be honest I'm a bit unclear on the answer which is why I cc'd the relevant teams =)

I would say that all of the currently listed things are de-facto blocking.

For rust-analyzer it depends on the feature really. Imo we don't need to fully support something (see async closures for example). A blocking concern is if the feature degrades the user experience by existing while rust-analyzer hasn't implemented it yet, think new syntax that r-a can't parse -> bogus diagnostics, type inference changes -> bogus diagnostics. I think in fact, its mainly whether a change will make r-a emit false diagnostics due to lacking support, though there might be more things I can't think of right now.

jackh726 · 2025-01-23T20:54:24Z

src/stabilization_guide.md

-The rest of the team members will review the proposal. If the final
-decision is to stabilize, we proceed to do the actual code modification.
+The stabilization report is typically posted as the main comment on the stabilization PR (see the next section).
+If you'd like to develop the stabilization report incrementally, we recommend adding it to 


incomplete: "adding it to"...

Oh yeah, I never finished. I was going to suggest the practice of adding the stabilization report to the unsafe book and updating it incrementally (e.g., with a list of PRs, if nothing else).

jackh726 · 2025-01-23T20:58:02Z

src/stabilization_guide.md

@@ -194,3 +164,23 @@ if something { /* XXX */ }
 [Rust by Example]: https://github.com/rust-lang/rust-by-example
 [`Unstable Book`]: https://doc.rust-lang.org/unstable-book/index.html
 [`src/doc/unstable-book`]: https://github.com/rust-lang/rust/tree/master/src/doc/unstable-book
+
+## Lang team nomination


Maybe just change this section to team nominations, and put the lang team as the first item (and emphasize)?

Also, a discussion for another place, but this made me think: Is it all that great to nominate things immediately? There are usually plenty of comments on things and it might be worth delaying the teams discussing things until those immediate comments get addressed.

+1 to the more general title. I wondered the same thing about when to nominate. I don't know the right answer.

I guess saying "when comments die down, or if you don't get any comments, nominate"

jackh726 · 2025-01-23T20:59:54Z

src/stabilization_guide.md

+When you feel the PR is ready for consideration by the lang team, you can [nominate the PR](https://lang-team.rust-lang.org/how_to/nominate.html) to get it on the list for discussion in the next meeting. You should also cc the other interacting teams to review the report:
+
+* `@rust-lang/types`, to look for type system interactions
+* `@rust-lang/compiler`, to vouch for implementation quality


Maybe this should be an explicit step? For either the compiler team as a whole, or at least just the "owner" of the implementation to be on board with stabilization. Otherwise, "everything" should be compiler nominated?

Yes, this is a good question. My feeling is that both compiler and types ought to have a process of assigning one person to prepare a summary for others to read, but I felt that needed more discussion before I wrote it in here. I should probably open a tracking issue on this overall topic.

To be honest, lang should have that process too :)

traviscross · 2025-01-23T22:54:56Z

src/stabilization_report_template.md

+  - (Positive/negative) Interface tests? (e.g. compiler cli interface)
+  - Maybe link to test folders or individual tests (ui/codegen/assembly/run-make tests, etc.)
+  - Are there any (intentional/unintentional) gaps in test coverage?
+


Suggested change

Consider what the "edges" of this feature are. We're particularly interested in seeing tests that assure us about exactly what nearby things we're not stabilizing.

Going even further:

Suggested change

Consider what the "edges" of this feature are. We're particularly interested in seeing tests that assure us about exactly what nearby things we're not stabilizing.

Within each test, include a comment at the top describing the purpose of the test and what set of invariants it intends to demonstrate. This is a great help to those reviewing the tests at stabilization time.

Similarly, please consider including, when appropriate, `//@ reference:` annotations to connect each test with the corresponding item in the Reference.

In reviewing the tests for the arbitrary self types stabilization, I'm reminded how helpful it is for each test to describe at the top what it is intending to demonstrate, so it's worth mentioning that.

It's also probably worth mentioning here the utility of the Reference annotations, but that raises an interesting ordering question. We merge tests ahead of the stabilization, generally, but then we don't merge the Reference PR until after the stabilization. So we'd either need to merge the tests with dangling references (to identifiers in unmerged Reference PRs) or perhaps these references could be added to the tests in the stabilization PR itself. Or they could be added later, but then these helpful things aren't there when reviewing the stabilization.

(Another wilder option is that we merge the Reference into rust-lang/rust itself, as was recently done with the dev guide, and then the Reference PR becomes a part of the stabilization PR. We're probably not yet ready to do that in general, and one challenge with this is that it's often useful to us to directly push our own commits to a Reference PR branch rather than going back and forth with the author, but permissions on rust-lang/rust aren't currently set in a way that would enable that.)

@ehuss, @nikomatsakis, what do you think?

Urgau · 2025-01-24T19:31:14Z

src/implementing_new_features.md

+
+## Call for testing
+
+Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.


There is also the call-for-testing section in TWIR. I think some of us have been trying to use it more often¹.

It might useful to mention it for feature that are maybe to small for a full scale blog post. Although from my experience it effect is minimal at best.

Footnotes

https://github.com/rust-lang/rust/issues/131204#issuecomment-2569314526 ↩

IME it's still really hard to find, because you have to actually read TWiR, a proper blog post is likely significantly more visible

oli-obk · 2025-01-24T20:20:10Z

src/stabilization_report_template.md

+
+## Type system and execution rules
+
+### What compilation-time checks are done that are needed to prevent undefined behavior?


Similar question: Does the feature's implementation need checks to prevent UB or is it sound by default and needs opt in in places to perform the dangerous/unsafe operations? If it is not sound by default, what is the rationale?

WaffleLapkin · 2025-01-24T23:11:54Z

src/implementing_new_features.md

+
+## Call for testing
+
+Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.


nitpick: for accessibility it is generally advisable to have link text describe what the link actually is, since one of the navigation tools for blind folks is "jump between links".

I would suggest something like this:

Suggested change

Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.

Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three example blog posts: [The push for GATs stabilization](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html), [Async Closures MVP: Call for Testing!](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html), [Changes to `impl Trait` in Rust 2024](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.

... and also argue that it's nicer for abled folks as well -- now you can more clearly see that there are 3 links and it's clear what each blog post is about, so you don't have to click on it to learn that.

Alternatively, could also just list them out:

"[...] and issue a call for testing." Example blog posts:

The push for GATs stabilization

Async Closures MVP: Call for Testing!

Changes to impl Trait in Rust 2024

WaffleLapkin · 2025-01-24T23:13:32Z

src/implementing_new_features.md

+
+## Affiliated work
+
+Once the feature is supported by rustc, there is other associated work that needs to be done to give users a complete experience:


I would say that all of the currently listed things are de-facto blocking.

WaffleLapkin · 2025-01-24T23:15:51Z

src/stabilization_guide.md

-The rest of the team members will review the proposal. If the final
-decision is to stabilize, we proceed to do the actual code modification.
+The stabilization report is typically posted as the main comment on the stabilization PR (see the next section).
+If you'd like to develop the stabilization report incrementally, we recommend adding it to 

 ## Stabilization PR


Suggested change

## Stabilization PR

## Stabilization PR for a language feature

Given the note just below...

WaffleLapkin · 2025-01-24T23:20:59Z

src/stabilization_guide.md

This file contains the following:

Once we have decided to stabilize a feature, we need to have
a PR that actually makes that stabilization happen. These kinds
of PRs are a great way to get involved in Rust, as they take
you on a little tour through the source code.

And I'm not sure how accurate this is.

First of all the "Once we have decided to stabilize a feature" part is too vague. How would a new contributor know which features we decided to stabilize? Additionally the decision and stabilization report need to be done by someone with a good knowledge of the feature, a new contributor just isn't suitable for that.

I feel like this paragraph is misguiding, as stabilization is usually an intertwined process involving multiple teams, sometimes confusing changes (like changing lints that don't make sense anymore), checking many components, etc. If for library features it might be the case that a novice can craft a stabilization PR, for language features, more often than not that's not the case.

WaffleLapkin · 2025-01-24T23:27:34Z

src/stabilization_guide.md

Syntax for accessing features is outdated:

-gate_feature_post!(&self, pub_restricted, span, "`pub(restricted)` syntax is experimental"); +gate_all!(pub_restricted, "`pub(restricted)` syntax is experimental");

and

-if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } +if self.tcx.features().async_fn_in_dyn_trait() { /* XXX */ }

WaffleLapkin · 2025-01-24T23:28:40Z

src/stabilization_guide.md

+* `@rust-lang/types`, to look for type system interactions
+* `@rust-lang/compiler`, to vouch for implementation quality
+* `@rust-lang/opsem`, but only if this feature interacts with unsafe code and can create undefined behavior
+* `@rust-lang/libs-api`, but only if there are additions to the standard library


Note that people who are not members of the org cannot use team pings.

It is possible for PR author to ask the reviewer to cc relevant teams on the PR author's behalf, but yes, this can be confusing

est31 · 2025-01-25T04:23:11Z

src/stabilization_report_template.md

+
+- What does the test coverage landscape for this feature look like?
+  - (Positive/negative) Behavioral tests?
+  - (Positive/negative) Interface tests? (e.g. compiler cli interface)


the big categories I think are:

tests for compiler errors when you use the feature wrongly or make simple mistakes

tests for the feature itself:

tests for limits of the feature (so failing compilation)

run-pass tests that ensure that the feature works

est31 · 2025-01-25T04:24:29Z

src/stabilization_report_template.md

+
+### Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those?
+
+## Has a call-for-testing period been conducted? If so, what feedback was received?


Maybe it would be useful to mention any OSS nightly users there. usually when a feature works, feedback is quite scant but "searched grep.app for #![feature(...)] and had N results" gives a good gauge I think.

jieyouxu

Thanks for working on this!

jieyouxu · 2025-01-25T07:01:20Z

src/implementing_new_features.md

+
+## Call for testing
+
+Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.


IME it's still really hard to find, because you have to actually read TWiR, a proper blog post is likely significantly more visible

jieyouxu · 2025-01-25T07:02:47Z

src/implementing_new_features.md

+
+## Call for testing
+
+Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.


Alternatively, could also just list them out:

"[...] and issue a call for testing." Example blog posts:

The push for GATs stabilization

Async Closures MVP: Call for Testing!

Changes to impl Trait in Rust 2024

jieyouxu · 2025-01-25T07:03:48Z

src/implementing_new_features.md

+* Extending rustfmt to format any new syntax;
+* Extending rust-analyzer;
+* Documenting the feature in the Rust reference;
+* ...


Less often, but sometimes new features may involve coordination with cargo as well

jieyouxu · 2025-01-25T07:06:18Z

src/stabilization_guide.md

-feature agrees with stabilizing this feature, they will
-start the FCP (final-comment-period) process by commenting
+Author a stabilization report using the [template found in this repository][srt].
+Stabilization reports summarize the work that has been done since the RFC.


Suggestion: I think it's also important to summarize design decisions and deviations that have been made since the RFC was accepted (esp. decisions that were FCP'd or otherwise accepted by relevant teams). Many times, the final stabilized feature only vaguely resembles the originally proposed RFC (probably more faithful in preserving intention/use cases but less the exact form).

jieyouxu · 2025-01-25T07:10:12Z

src/stabilization_guide.md

+* `@rust-lang/types`, to look for type system interactions
+* `@rust-lang/compiler`, to vouch for implementation quality
+* `@rust-lang/opsem`, but only if this feature interacts with unsafe code and can create undefined behavior
+* `@rust-lang/libs-api`, but only if there are additions to the standard library


It is possible for PR author to ask the reviewer to cc relevant teams on the PR author's behalf, but yes, this can be confusing

jieyouxu · 2025-01-25T07:14:57Z

src/stabilization_report_template.md

+  - (Positive/negative) Behavioral tests?
+  - (Positive/negative) Interface tests? (e.g. compiler cli interface)


Remark: I suggested this but the wording feels too vague to me, would be great if anyone has any suggestions for categories of test coverage.

stabilization template, docs

e4ee951

nikomatsakis force-pushed the stabilization-template branch from 8d2e702 to e4ee951 Compare January 23, 2025 20:27

jackh726 reviewed Jan 23, 2025

View reviewed changes

Update src/implementing_new_features.md

c63baad

traviscross reviewed Jan 23, 2025

View reviewed changes

jieyouxu added S-waiting-on-review Status: this PR is waiting for a reviewer to verify its content T-compiler Relevant to compiler team T-lang Relevant to lang team T-types Relevant to types team T-rust-analyzer Relevant to rust-analyzer team labels Jan 24, 2025

jieyouxu self-assigned this Jan 24, 2025

Urgau reviewed Jan 24, 2025

View reviewed changes

oli-obk reviewed Jan 24, 2025

View reviewed changes

WaffleLapkin reviewed Jan 24, 2025

View reviewed changes

est31 reviewed Jan 25, 2025

View reviewed changes

jieyouxu reviewed Jan 25, 2025

View reviewed changes


		## Affiliated work

		Once the feature is supported by rustc, there is other associated work that needs to be done to give users a complete experience:


	Consider what the "edges" of this feature are. We're particularly interested in seeing tests that assure us about exactly what nearby things we're not stabilizing.

+Consider what the "edges" of this feature are.  We're particularly interested in seeing tests that assure us about exactly what nearby things we're not stabilizing.
+Within each test, include a comment at the top describing the purpose of the test and what set of invariants it intends to demonstrate.  This is a great help to those reviewing the tests at stabilization time.
+Similarly, please consider including, when appropriate, `//@ reference:` annotations to connect each test with the corresponding item in the Reference.


		## Call for testing

		Once the implementation is complete, the feature will be available to nightly users, but not yet part of stable Rust. This is a good time to write a blog post on [one of the Rust blogs](https://github.com/rust-lang/blog.rust-lang.org/) and issue a call for testing (here are three [example](https://blog.rust-lang.org/2021/08/03/GATs-stabilization-push.html) [blog](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing.html) [posts](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) to give you the idea). The post should highlight how the feature works, what areas you'd like people to play with, and how they can supply feedback.


		## Type system and execution rules

		### What compilation-time checks are done that are needed to prevent undefined behavior?

	## Stabilization PR
	## Stabilization PR for a language feature


		### Are there extensions to this feature that remain unstable? How do we know that we are not accidentally committing to those?

		## Has a call-for-testing period been conducted? If so, what feedback was received?

		- (Positive/negative) Behavioral tests?
		- (Positive/negative) Interface tests? (e.g. compiler cli interface)

stabilization template, docs #2219

Are you sure you want to change the base?

stabilization template, docs #2219

Conversation

nikomatsakis commented Jan 23, 2025

jackh726 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

traviscross Jan 25, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Footnotes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jieyouxu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jieyouxu Jan 25, 2025 • edited by WaffleLapkin Loading

Choose a reason for hiding this comment

traviscross Jan 25, 2025 •

edited

Loading

jieyouxu Jan 25, 2025 •

edited by WaffleLapkin

Loading