|
| 1 | +- Start Date: 2023-10-3 |
| 2 | +- RFC PR: [rust-lang/rfcs#3505](https://github.com/rust-lang/rfcs/pull/3505) |
| 3 | + |
| 4 | +# Summary |
| 5 | +[summary]: #summary |
| 6 | + |
| 7 | +The [rustdoc-types](https://crates.io/crates/rustdoc-types) crate will go from being individually maintained to being officially maintained by the rustdoc team. |
| 8 | + |
| 9 | +# Motivation |
| 10 | +[motivation]: #motivation |
| 11 | + |
| 12 | +[`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 provide 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. E.g: |
| 13 | + |
| 14 | +| Name | Purpose | |
| 15 | +|--|--| |
| 16 | +| [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. | |
| 17 | +| [Enselic/cargo-public-api] | Compares the public API of two crates. Used to check for semver violations. | |
| 18 | +| [obi1kenobi/trustfall-rustdoc-adapter] | Higher-level database-ish API for querying Rust API's. Used by [obi1kenobi/cargo-semver-checks] | |
| 19 | + |
| 20 | +[awslabs/cargo-check-external-types]: https://github.com/awslabs/cargo-check-external-types/blob/dc15c5ee7674a495d807481402fee46fdbdbb140/Cargo.toml#L16 |
| 21 | + |
| 22 | +[Enselic/cargo-public-api]: https://github.com/Enselic/cargo-public-api/blob/19f15ce4146835691d489ec9db3518e021b638e8/public-api/Cargo.toml#L27 |
| 23 | + |
| 24 | +[obi1kenobi/trustfall-rustdoc-adapter]: https://github.com/obi1kenobi/trustfall-rustdoc-adapter/blob/92cbbf9bc6c9dfaf40bba8adfbc56c0bb7aff12f/Cargo.toml#L15 |
| 25 | + |
| 26 | +[obi1kenobi/cargo-semver-checks]: https://github.com/obi1kenobi/cargo-semver-checks |
| 27 | + |
| 28 | +[RFC 1977]: https://rust-lang.github.io/rfcs/1977-public-private-dependencies.html |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | +Additionally, if an update to `rustdoc-json-types` happens while I'm away from a computer for an extended period of time, there will be a delay in this update being published on crates.io. This happened with format_version 29, which was merged on [April 8th](https://github.com/rust-lang/rust/commit/537aab7a2e7fe9cdf50b5ff18485e0793cd8db62), |
| 33 | +but was only published to crates.io on |
| 34 | +[April 19th](https://github.com/aDotInTheVoid/rustdoc-types/commit/ad92b911488dd42681e3dc7e496f777f556a94f6), due to personal reasons. |
| 35 | +[This almost happened previously](https://github.com/aDotInTheVoid/rustdoc-types/issues/25), but was avoided due to the bors queue being quiet at the time. |
| 36 | + |
| 37 | +# Guide-level explanation |
| 38 | +[guide-level-explanation]: #guide-level-explanation |
| 39 | + |
| 40 | +This involves: |
| 41 | + |
| 42 | +1. Moving the [github.com/aDotInTheVoid/rustdoc-types](https://github.com/aDotInTheVoid/rustdoc-types/) repo to the `rust-lang` organization, and make `rust-lang/rustdoc` maintainers/owners. |
| 43 | +2. Move ownership of `rustdoc-types` on crates.io to the rustdoc team. |
| 44 | + |
| 45 | +# Reference-level explanation |
| 46 | +[reference-level-explanation]: #reference-level-explanation |
| 47 | + |
| 48 | +`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 as 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. |
| 49 | + |
| 50 | +Republishing `rustdoc-json-types` as `rustdoc-types` is done with [a script](https://github.com/aDotInTheVoid/rustdoc-types/blob/17cbe9f8f07de954261dbb9536c394381770de7b/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. |
| 51 | + |
| 52 | +The update/publishing process will be moved to T-rustdoc. In the medium term, I (`@aDotInTheVoid`) will still do it, but |
| 53 | +- In an official capacity |
| 54 | +- With bus factor for when I stop. |
| 55 | + |
| 56 | +We (T-rustdoc) will continue to publish a new version of the `rustdoc-types` crate |
| 57 | +every time the upstream implementation changes, and these will be versioned with |
| 58 | +normal SemVer. Changes to rustdoc-json in `rust-lang/rust` will not be accepted |
| 59 | +if they would make it not possible to publish `rustdoc-types` (eg: using `rustc_*` |
| 60 | +crates, or nightly features). |
| 61 | + |
| 62 | +## Actual Mechanics of the move |
| 63 | + |
| 64 | +### GitHub |
| 65 | + |
| 66 | +GitHub has a [list of requirements](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository) for transferring repositories. T-infra will handle the permissions of moving the repository into the rust-lang GitHub organization. |
| 67 | + |
| 68 | +At the end of this we should have a moved the [`aDotInTheVoid/rustdoc-types`] |
| 69 | +repo into the rust-lang GitHub org. T-rustdoc will have `maintain` permissions |
| 70 | +(via the [team repo](https://github.com/rust-lang/team/)). |
| 71 | + |
| 72 | +### crates.io |
| 73 | + |
| 74 | +crates.io ownership is managed [via the command line](https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner). |
| 75 | + |
| 76 | +I will run the following commands to move ownership. |
| 77 | + |
| 78 | +``` |
| 79 | +cargo owner --add github:rust-lang:rustdoc |
| 80 | +cargo owner --add rust-lang-owner |
| 81 | +cargo owner --remove aDotInTheVoid |
| 82 | +``` |
| 83 | + |
| 84 | +The `rust-lang-owner` is needed because team owners cannot add new owners. |
| 85 | + |
| 86 | +# Drawbacks |
| 87 | +[drawbacks]: #drawbacks |
| 88 | + |
| 89 | +- Adds additional maintenance burden to rustdoc team. |
| 90 | +- One-time maintenance burden to infra team to support move. |
| 91 | + |
| 92 | + |
| 93 | +# Rationale and alternatives |
| 94 | +[rationale-and-alternatives]: #rationale-and-alternatives |
| 95 | + |
| 96 | +- We could keep `rustdoc-types` as a personal project. This preserves the status quo (and is what will happen if this RFC (or something similar) isn't adopted). This is undesirable because |
| 97 | + - Bus factor: If I am unable or unwilling to maintain `rustdoc-types`, we cause a load of unnecessary churn when it becomes out of sync with the in-tree `rustdoc-json-types` |
| 98 | +- We could bundle `rustdoc-types` through rustup. This is undesirable as it means users can't depend on it in stable rust, and can't depend on multiple versions. |
| 99 | +- We could publish `rustdoc-json-types` directly from `rust-lang/rust`. However |
| 100 | + - `rust-lang/rust` doesn't currently publish to crates.io. |
| 101 | + - `rustdoc-json-types` doesn't currently bump the version field in `Cargo.toml` |
| 102 | + - It may be desirable to one day use different types for rustdoc serialization vs users deserialization |
| 103 | + |
| 104 | + Reasons for this: |
| 105 | + - It could enable performance optimizations by avoiding allocations into strings |
| 106 | + - It could help with stabilization: |
| 107 | + - Allows making structs/enums `#[non_exhaustive]` |
| 108 | + - Allows potentially supporting multiple format versions. |
| 109 | + - `rustdoc-types` is a nicer name, and what people already depend on. |
| 110 | + |
| 111 | +# Prior art |
| 112 | +[prior-art]: #prior-art |
| 113 | + |
| 114 | +- [Rust RFC 3119](https://rust-lang.github.io/rfcs/3119-rust-crate-ownership.html) establishes the Rust crate ownership policy. Under its categories, `rustdoc-types` would be an **intentional artifact** |
| 115 | +- [Some old zulip discussion about why `rustdoc-json-types` was created.](https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/JSON.20Format/near/223685843) What was said then is that if T-Rustdoc wants to publish a crate, it needs to go through an RFC. This is that RFC. |
| 116 | +- the [`cargo |
| 117 | + metadata`](https://doc.rust-lang.org/cargo/commands/cargo-metadata.html) |
| 118 | + command gives JSON information about a cargo package. The |
| 119 | + [cargo-metadata](https://docs.rs/cargo_metadata/latest/cargo_metadata/) crate |
| 120 | + provides access to this. Instead of being a export of the cargo-side type declarations, |
| 121 | + it's manually written, and not officially maintained. This has [lead to compatibility issues](https://github.com/oli-obk/cargo_metadata/issues/240) |
| 122 | + in the past. Despite being stable, the exact compatibility story [isn't yet determined](https://github.com/rust-lang/cargo/issues/12377). |
| 123 | + |
| 124 | +# Unresolved questions |
| 125 | +[unresolved-questions]: #unresolved-questions |
| 126 | + |
| 127 | +None yet |
| 128 | + |
| 129 | +# Future possibilities |
| 130 | +[future-possibilities]: #future-possibilities |
| 131 | + |
| 132 | +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. |
0 commit comments