Rework the feature lifecycle #55
Conversation
There was a problem hiding this comment.
A general note on risk/effort/wait time tradeoff should be mentioned. E.g. that one can start with a PR first and do the ACP later but that faces a higher risk of wasting effort. But on the other hand there's always a possibility that things will get rejected during later parts of the process up to the FCP.
To an experienced contributor this is all obvious but it might not be to a newcomer.
src/feature-lifecycle/summary.md
Outdated
|
|
||
| ## API design exploration | ||
|
|
||
| Once a feature is deemed suitable for inclusion in the standard library, the exact design should be iterated on to find the best way to express it as a Rust API. This iteration should happen in community forums such as [Rust internals](https://internals.rust-lang.org/) where all members of the community can comment and propose improvements. |
There was a problem hiding this comment.
such as Rust internals
"Such as" implies that there might be other appropriate places. Are there? If so, which ones?
src/feature-lifecycle/summary.md
Outdated
| who will evaluate the proposal and accept it if they are optimistic that the proposal will | ||
| be merged and pass its eventual FCP. | ||
|
|
||
| You can create an ACP in the `rust-lang/libs-team` repo using [this issue template](https://github.com/rust-lang/libs-team/issues/new?assignees=&labels=api-change-proposal%2C+T-libs-api&template=api-change-proposal.md&title=%28My+API+Change+Proposal%29). This should include a sketch of the proposed API, but does not have to be the final design that will be implemented. |
There was a problem hiding this comment.
It looks like this issue template links to the deleted api-change-proposals.md page. The template should probably be changed before merging this.
There was a problem hiding this comment.
I think you misunderstood :) I mean in the template you show, there is a link to https://std-dev-guide.rust-lang.org/feature-lifecycle/api-change-proposals.html which this PR seems to delete. So that link would be dead after this merges.
src/feature-lifecycle/summary.md
Outdated
| Keep the following points in mind during the discussion: | ||
| - Resist the temptation to make the API overly general since this tends to increase complexity and lowers the chance of it being accepted by the library API team. Instead, try to stay focused on the problem that needs solving. | ||
| - An alternative that should *always* be considered is simply adding this feature via a third party crate. This is even possible when adding new methods to standard library types by using extension traits. | ||
| - In the case of "convenience" functions which are simply shorthands for something that is already possible with existing APIs, the cost of extending the standard library surface should be weighed against the ergonomic impact of the new functions. |
There was a problem hiding this comment.
the cost of extending the standard library surface
Could this be more specific about what this cost is? The increase in documentation length? The maintenance cost (due to the stability guarantees, I imagine many APIs in std will rarely if ever need to change)?
I mention this because I think improving ergonomics is a very valid reason for introducing new APIs and shouldn't lightly be dismissed.
|
In #56 I removed the old page on ACPs. Sorry for the merge conflict. I guess in the new layout this should go in chapter 2. |
|
I am planning to move https://rustc-dev-guide.rust-lang.org/stability.html from the rustc guide to the std guide soon, but I'll wait until this is merged to avoid conflicts. |
Amanieu
force-pushed
the
feature-lifecycle-rework
branch
from
192d743
to
4b6d538
Compare
Amanieu
force-pushed
the
feature-lifecycle-rework
branch
from
4b6d538
to
0a1b503
Compare
|
I've rebased and address all the feedback. |
generated from commit 64f2065
This PR reworks the workflow for introducing new APIs to the standard library. This is the result of extensive discussion in the 2023 libs meetup.
Major changes include:
cc @rust-lang/libs-api