Move rustdoc-types crate to T-Rustdoc ownership.

[aDotInTheVoid]

Rendered

CC @rust-lang/rustdoc @rust-lang/infra

[Manishearth]

issue: I think we should carefully document what our versioning strategy is.

[aDotInTheVoid]

For the crate, or the FORMAT_VERSION constant?

For the crate, the current approach is "Follow semver, and don't release 1.0.0 until stabilization". The post 1.0.0 versioning strategy will be figured out in concert with designing the format for post-stabilization evolution.

How much detail on versioning strategy do you think this RFC needs? From a users POV, their should be no change from this, and new releases will be published in the same fashion as before.

[Manishearth]

The crate. We should both:

• Document what we plan to do in the near future
• Make a clear commitment; do we plan to do that for the forseeable future, or do we want flexibility to change how we do it. Are we going to make a release every time it changes? Do we guarantee that we will always pair rustdoc JSON changes with rustdoc-types changes? Or is it acceptable if we change rustdoc JSON in a way that breaks rustdoc-types but not immediately publish a new version?

It's going to be an official Rust artefact, we need to be a bit clearer to our users.

[pietroalbini]

From an infra point of view, I think we can just remove the GitHub section, and have someone from T-rustdoc ping infra on Zulip when the move needs to happen. Infra will then handle it like all repository moves we do.

[aDotInTheVoid]

does this mean we're going to abandon rustdoc_json_types's FORMAT_VERSION constant in favor of updating the package version

No, not at all. We're going to keep increasing FORMAT_VERSION whenever we change the format, and versioning the crates.io release according to SemVer. Those 2 versions are not necessarily linked, eg we could go from pub struct Id(pub String) to pub struct Id(String) without needing to bump FORMAT_VERSION, but it would be a breaking change for the cargo version.

[Mark-Simulacrum]

I'm not sure what this is trying to say here. "crate" is in crates.io, not GitHub typically. I also don't see what "T-infra as owners" means -- but it seems pretty surprising for T-infra to be an owner. Do we mean the rust-lang-owner account on crates.io?

The other sections don't seem to elaborate on this sentence.

I at least am not comfortable with infra being an owner for this crate or accompanying repository: it feels very much out of our general scope as a team, and very much "just" a rustdoc concern.

[aDotInTheVoid]

I'm not sure what this is trying to say here. "crate" is in crates.io, not GitHub typically.

Gah sorry, this is my bad writing. I mean the aDotInTheVoid/rustdoc-types repo.

I at least am not comfortable with infra being an owner for this crate or accompanying repository: it feels very much out of our general scope as a team, and very much "just" a rustdoc concern.

Agreed. I meant this in terms of GitHub permissions, not who'se maintaining the crate/repo. If the repo admin permissions should instead go to rust-lang-owner (instead of the infra team or even the rustdoc team) I'm happy to do that.

[Mark-Simulacrum]

Maybe I'm confused, but aren't we moving that repo into the rust-lang org? If so, then permissions are granted via the team repo and should only consist of teams that need access (in this case, presumably rustdoc).

Infra has access if needed through the org admins, but that is true for all repos in the org so generally doesn't need specific enumeration.

[Mark-Simulacrum]

In any case, I'm happy with the intent now that I understand it :)

[aDotInTheVoid]

Maybe I'm confused, but aren't we moving that repo into the rust-lang org?

Yes

If so, then permissions are granted via the team repo and should only consist of teams that need access.

Ah. That makes things even simpler.

[camelid]

Thanks for writing this up! And my apologies for my delay in reviewing; I've been trying to catch up on RFCs. As mentioned on Zulip, I definitely agree with the principle of moving this crate to team ownership. However, I would rather not require two PRs (one to make the change and one to update rustdoc-types) every time we increase the FORMAT_VERSION or otherwise change the JSON API. I don't feel super strong about this, but it does seem unfortunate and like it would be easy for rustdoc-types to fall out of date. See my comments below for more detail.

[camelid]

I'm a little unclear about how this could ever happen. Do you mind giving an example, and/or clarifying the wording to be more precise?

[aDotInTheVoid]

Stuff that depends on rust-lang/rust's "weird" build environment. In paticular:

1. Access to rustc_private crates. We can't use types like DefId or Symbol here (at least on the user facing side).
2. Using nightly language features/knowing the compiler version(s) being used to build

I'll add these to the RFC.

[camelid]

Hmm, I am a little concerned about having a separate repo because it would mean every PR that increases FORMAT_VERSION would also necessitate a separate PR to a different repo. Is there a downside to publishing from a folder in rust-lang/rust instead (or maybe even a git subtree)? See also my comments below about merging it with rustdoc-json-types, though my main concern is requiring multiple PRs.

[aDotInTheVoid]

though my main concern is requiring multiple PRs.

FWIW, this is how it's always been done, but that's defiantly not sufficient justification that it's the best way.

Is there a downside to publishing from a folder in rust-lang/rust instead (or maybe even a git subtree)?

1. Can't tag the git repo with creates.io version
   • I'm not sure how compelling this is
2. No way to diff view diff between releases
   • rust-lang/rustdoc-types@v0.29.1...v0.30.0 is nice to see.
   • Know way (AFAIKT) to get something like this in rl/r (without github showing changes from the rest of the repo)
3. Having the crate be a small repo makes it easier to depend on it via cargo's git feature (rather than having cargo clone rl/r). update.sh: Make user, repo, and branch easy to change rustdoc-types#14
4. Requires re-engineering release procedures, and it's unclear how that would work in rust-lang/rust
   • Are we now going to cd into a local clone of rust-lang/rust and cargo publish? This is involved to
   • Alternatively, is rust-lang/rust CI going to autopublish? This is a whole can of worms, and it'd be much easier to set up auto-publishing on it's own repo.
   • Changelog generation get's tricky if it needs to be done in the PR that implements it.
     • Can't know the date it will be published to crates.io before merging, due to unpredictable bors delay
       • But maybe we don't need this in the changelog, it's not super intuitive how this is ties to crates.io (not rustup dates)
5. I kinda like that the publish happens later, and gets another pass on it before going out to users:
   • A couple of big sweeping compiler changes have made breaking changes to rustdoc-json. (Remove the ty field from type system Consts rust#125958, Implement minimal, internal-only pattern types in the type system rust#120131). Knowing that as long as FORMAT_VERSION was bumped we'd be fine, (as everything else could be hashed out separately later) made this less stressful for me, and reduced workload on T-Compiler
   • But maybe this is just me wanting to keep control of things, and want to hoard responsibility withing T-Rustdoc. It feels kinda unhealthy somehow.

[aDotInTheVoid]

Whats your concern with multiple PR's? Given that there's already a publish step, I don't think it cuts down on work (unless we autopublish from rust-lang/rust PR's, which I'm not fully comfortable with)

We could land this now (primarily for bus-factor reasons), and then move change things separately if it becomes a problem.

[camelid]

Whats your concern with multiple PR's? Given that there's already a publish step, I don't think it cuts down on work (unless we autopublish from rust-lang/rust PR's, which I'm not fully comfortable with)

Fair enough since all that's needed to update the repo is to run a script.

We could land this now (primarily for bus-factor reasons), and then move change things separately if it becomes a problem.

Yeah, I guess that makes sense since it wouldn't even need a whole RFC for a small administrative change like that.

[camelid]

I kinda like that the publish happens later, and gets another pass on it before going out to users:

Ah, the impression I got from the RFC text was you wanted publishing to happen almost as soon as the format version changed. I agree that there's benefit to reviewing the changes before publishing a new crate version.

[camelid]

This seems irrelevant since we could just rename rustdoc-json-types to rustdoc-types.

[aDotInTheVoid]

That's fair.

[camelid]

FWIW we could use cfgs for this (like feature = "unstable_internal_rustdoc" for the internal rustdoc version). I don't think we'd want to maintain two completely separate versions of the API anyway, since it would be confusing to keep in sync.

[aDotInTheVoid]

Yeah, we should probably do that either way, to replace the increasing pile of regex we currently use.

[camelid]

@rfcbot concern out-of-tree (see above review)

[camelid]

@rfcbot reviewed

I'm ticking my box because my only concern is about the crate being out-of-tree (meaning outside of rust-lang/rust).

[camelid]

nits: (no need for a feature name if there's no actual feature)

Suggested change

	- Feature Name: `rustdoc_types_maintainers`
	- Start Date: 2023-10-3
	- Start Date: 2023-10-03

[camelid]

@rfcbot resolve out-of-tree

It sounds like being out of tree does make more sense overall, and we can always adjust this later. Good to get the bus factor dealt with no matter the precise details of the infrastructure.

[camelid]

@rfcbot resolve out-of-tree (see above review)

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[GuillaumeGomez]

Thanks for this PR! I'll make changes and then push it.

[GuillaumeGomez]

Took your commits, rebased them and renamed the RFC file in #3705. RFC has been merged, thanks everyone!