Skip to content

Commit 81fa8fc

Browse files
committed
Typo Fixes and Rearangement
1 parent 2997902 commit 81fa8fc

File tree

1 file changed

+26
-7
lines changed

1 file changed

+26
-7
lines changed

text/0000-rustdoc-types-maintainers.md

+26-7
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,23 @@ The [rustdoc-types](https://crates.io/crates/rustdoc-types) crate will go from b
1111
# Motivation
1212
[motivation]: #motivation
1313

14-
[`rustdoc-types`](https://crates.io/crates/rustdoc-types) is a crate published on crates.io. It is used by users of the unstable [rustdoc JSON](https://github.com/rust-lang/rust/issues/76578) backend to provided a type representing the output of `rustdoc --output-format json`.
14+
[`rustdoc-types`](https://crates.io/crates/rustdoc-types) is a crate published on crates.io. It is used by users of the unstable [rustdoc JSON](https://github.com/rust-lang/rust/issues/76578) backend to provided a type representing the output of `rustdoc --output-format json`. It's published on crates.io to be used by out-of-tree tools that take rustdoc-json as an input. Eg:.
1515

16+
| Name | Purpose |
17+
|--|--|
18+
| [awslabs/cargo-check-external-types] | Home-rolled version of [RFC 1977] "private dependencies". Checks if any types from the private dependency are used in a crate's public API. |
19+
| [Enselic/cargo-public-api] | Compares the public API of two crates. Used to check for semver violations. |
20+
| [obi1kenobi/trustfall-rustdoc-adapter] | Higher-level database-ish API for querying Rust API's. Used by [obi1kenobi/cargo-semver-checks] |
21+
22+
[awslabs/cargo-check-external-types]: https://github.com/awslabs/cargo-check-external-types/blob/dc15c5ee7674a495d807481402fee46fdbdbb140/Cargo.toml#L16
23+
24+
[Enselic/cargo-public-api]: https://github.com/Enselic/cargo-public-api/blob/19f15ce4146835691d489ec9db3518e021b638e8/public-api/Cargo.toml#L27
25+
26+
[obi1kenobi/trustfall-rustdoc-adapter]: https://github.com/obi1kenobi/trustfall-rustdoc-adapter/blob/92cbbf9bc6c9dfaf40bba8adfbc56c0bb7aff12f/Cargo.toml#L15
27+
28+
[obi1kenobi/cargo-semver-checks]: https://github.com/obi1kenobi/cargo-semver-checks
29+
30+
[RFC 1977]: https://rust-lang.github.io/rfcs/1977-public-private-dependencies.html
1631

1732
Currently I ([`@aDotInTheVoid`](https://github.com/aDotInTheVoid/)) maintain the `rustdoc-types` crate on [my personal github](https://github.com/aDotInTheVoid/rustdoc-types/). No-one else has either github or crates.io permissions. This means if I become unable (or more likely disinterested), the crate will not see updates.
1833

@@ -29,6 +44,10 @@ This involves:
2944
# Reference-level explanation
3045
[reference-level-explanation]: #reference-level-explanation
3146

47+
`rustdoc-types` is a republishing of the in-tree [`rustdoc-json-types`](https://github.com/rust-lang/rust/tree/b8536c1aa1973dd2438841815b1eeec129480e45/src/rustdoc-json-types) crate. `rustdoc-json-types` is a dependency of `librustdoc`, and is the canonical source of truth for the rustdoc-json output format. Changes to the format are made a a PR to `rust-lang/rust`, and will modify `src/rustdoc-json-types`, `src/librustdoc/json` and `tests/rustdoc-json`. None of this will change.
48+
49+
Republishing `rustdoc-json-types` as `rustdoc-types` is done with [a script](https://github.com/aDotInTheVoid/rustdoc-types/blob/577a774c2433beda669271102a201910c4169c0c/update.sh) so that it is as low maintenance as possible. This also ensures that all format/documentation changes happen in the rust-lang/rust repo, and go through the normal review process there.
50+
3251
`rustdoc-types` is a republishing of the in-tree [`rustdoc-json-types`](https://github.com/rust-lang/rust/tree/b8536c1aa1973dd2438841815b1eeec129480e45/src/rustdoc-json-types) crate. `rustdoc-json-types` is a dependency of `librustdoc`, and is the canonical source of truth for the canonical description of the rustdoc-json output format. Changes to the format are made a a PR to `rust-lang/rust`, and will modify `src/rustdoc-json-types`, `src/librustdoc/json` and `tests/rustdoc-json`. None of this will change.
3352

3453
However, the publishing of this to crates.io, so that it can be used by out-of-tree tools that take rustdoc-json as an input
@@ -50,7 +69,7 @@ Github has a [list of requirements](https://docs.github.com/en/repositories/crea
5069
- When you transfer a repository that you own to another personal account, the new owner will receive a confirmation email. The confirmation email includes instructions for accepting the transfer. If the new owner doesn't accept the transfer within one day, the invitation will expire.
5170
- N/A: Not transfering to
5271
- To transfer a repository that you own to an organization, you must have permission to create a repository in the target organization.
53-
- I (`@aDotInTheVoid`) don't have create-repo perms in the `rust-lang` org. Therefor I'll add a member of T-Infra as an owner to `aDotInTheVoid/rustdoc-types` (I can't add teams, as it's not in an org). They'll then move it to the repo to the `rust-lang` org. Once moved, T-Infra can become owners.
72+
- I (`@aDotInTheVoid`) don't have create-repo perms in the `rust-lang` org. Therefore I'll add a member of T-Infra as an owner to `aDotInTheVoid/rustdoc-types` (I can't add teams, as it's not in an org). They'll then move it to the repo to the `rust-lang` org. Once moved, T-Infra can become owners.
5473
- The target account must not have a repository with the same name, or a fork in the same network.
5574
- OK.
5675
- The original owner of the repository is added as a collaborator on the transferred repository. Other collaborators to the transferred repository remain intact.
@@ -62,7 +81,7 @@ At the end of this we should have a crate in the rust-lang github org with T-Rus
6281

6382
### crates.io
6483

65-
crats.io ownership is managed [via the command line](https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner).
84+
crates.io ownership is managed [via the command line](https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner).
6685

6786
I will run the following commands to move ownership.
6887

@@ -72,13 +91,13 @@ cargo owner --add rust-lang-owner
7291
cargo owner --remove aDotInTheVoid
7392
```
7493

75-
The `rust-lang-owner` is neaded because team owners cannot add new owners.
94+
The `rust-lang-owner` is needed because team owners cannot add new owners.
7695

7796
# Drawbacks
7897
[drawbacks]: #drawbacks
7998

80-
- Adds additional maintenence burden to rustdoc team.
81-
- One-time maintenece burden to infra team to support move.
99+
- Adds additional maintenance burden to rustdoc team.
100+
- One-time maintenance burden to infra team to support move.
82101

83102

84103
# Rationale and alternatives
@@ -108,5 +127,5 @@ None yet
108127
# Future possibilities
109128
[future-possibilities]: #future-possibilities
110129

111-
When the rustdoc-json feature is stabilized, we'll should release 1.0.0 to crates.io. How we can evolve the format post stabilization is an unanswered question. It's a blocker for stabilization, but not this RFC
130+
When the rustdoc-json feature is stabilized, we should release 1.0.0 to crates.io. How we can evolve the format post stabilization is an unanswered question. It's a blocker for stabilization, but not this RFC
112131

0 commit comments

Comments
 (0)