Skip to content

Commit

Permalink
Capture cargo team meeting notes and clean up
Browse files Browse the repository at this point in the history
  • Loading branch information
epage committed Jun 11, 2024
1 parent fcdb26b commit f38d7dc
Showing 1 changed file with 48 additions and 29 deletions.
77 changes: 48 additions & 29 deletions text/3416-feature-metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,14 @@

[summary]: #summary

This RFC is just meta tracking information for the three following RFCs:
This RFC adds a "detailed" feature definition:
```toml
[features]
# same as `foo = []`
foo = { enables = [] }
```

This is to unblock the following RFCs:

- [Cargo feature descriptions](https://github.com/rust-lang/rfcs/pull/3485)
- [Cargo feature deprecation](https://github.com/rust-lang/rfcs/pull/3486)
Expand Down Expand Up @@ -68,20 +75,11 @@ features are enabled by a given feature. For example,

All other keys are described in their individual RFCs.

# Reference-level explanation
## General Implementation & Usage

[reference-level-explanation]: #reference-level-explanation

`enables` will take the place of the feature dependency array that currently
exists. Semantics will remain unchanged.

This is a required key. If there are no requirements, an empty list should be
provided (`enables = []`). This content is already in the index.

# General Implementation & Usage

Use cases for this information will likely develop with time, but one of the
simplest applications is for information output with `cargo add`:
Use cases for these new keys will likely develop with time,
but one of the simplest applications is for information output with `cargo
add`:

```text
crab@rust foobar % cargo add regex
Expand All @@ -105,17 +103,23 @@ crab@rust foobar % cargo add regex
Features like `aho-corasick`, `memchr`, or `use_std` would likely be
`public = false` since they aren't listed on the crate landing page.

## Implementation note: sort order
# Reference-level explanation

[reference-level-explanation]: #reference-level-explanation

`enables` will take the place of the feature dependency array that currently
exists. Semantics will remain unchanged.

In general, any tool that renders features (`rustdoc`, `cargo add`) should
attempt to present them in the following way:
This is a required key. If there are no requirements, an empty list should be
provided (`enables = []`). This content is already in the index.

- Display default features first
- Display non-default but stable features next (can be in a separate section)
- Display deprecated features last (can be in a separate section)
- Do not display private features unless receiving a flag saying to do so (e.g.
`--document-private-items` with `rustdoc`)
- If ordering is not preserved, present the features alphabetically
The availability of this new syntax should not require an MSRV bump.
This means we need to make sure that if you use `feature_name = []` in your `Cargo.toml`,
then the published `Cargo.toml` should as well.
However, we leave it as an implementation detail whether using `feature_name = { enables =[] }`
requires an MSRV bump for users of your published package as we have not been
actively streamlining the workflow for maintaining separate development and
published MSRVs.

# Drawbacks

Expand All @@ -128,6 +132,23 @@ attempt to present them in the following way:

[rationale-and-alternatives]: #rationale-and-alternatives

This RFC has no impact on the Index Summaries.
Future RFCs will need to work with that.

## Naming

- `enables` reads better on the line than `enable`
- `enables` is likely an easier word for non-native speakers than `activates`
- `required` is used elsewhere to say "this should automatically be available if requirements are met"

## Schema

We could split the special feature syntax (`dep:`, etc) as distinct fields
but we'd prefer trivial conversion from the "simple" schema to the "detailed" schema,
like `dependencies`.
However, we likely would want to prefer using new fields over adding more syntax,
like with [disabling default features](https://github.com/rust-lang/cargo/issues/3126).

# Prior art

[prior-art]: #prior-art
Expand All @@ -140,12 +161,10 @@ attempt to present them in the following way:

[future-possibilities]: #future-possibilities

- A `rust-version` field that could indicate e.g. `rust-version = "nightly"` or
`rust-version = "1.65"` to specify a MSRV for that feature. See:
<https://github.com/rust-lang/rfcs/pull/3416#discussion_r1174478461>
- `cargo add` can show the `doc` and `deprecated` summary with the listed
features.
- [`cargo-info`] can use this information to provide feature descriptions.
- [Cargo feature descriptions](https://github.com/rust-lang/rfcs/pull/3485)
- [Cargo feature deprecation](https://github.com/rust-lang/rfcs/pull/3486)
- [Cargo feature visibility](https://github.com/rust-lang/rfcs/pull/3487)
- [Cargo feature stability](https://github.com/rust-lang/cargo/issues/10881)

[cargo #12335]: https://github.com/rust-lang/cargo/issues/12235
[cargo #10882]: https://github.com/rust-lang/cargo/issues/10882
Expand Down

0 comments on commit f38d7dc

Please sign in to comment.