diff --git a/procedures/crates.md b/procedures/crates.md new file mode 100644 index 00000000..fe013515 --- /dev/null +++ b/procedures/crates.md @@ -0,0 +1,147 @@ +# Third-party and out-of-tree crates +This document describe the guidelines for creating out-of-tree crates for use in the compiler and +using third-party crates within the compiler. These guidelines were originally discussed at the +Rust All Hands 2019 by the compiler team and others; and then at the +[01/03/2019 steering meeting][steering_meeting]. + +[steering_meeting]: https://github.com/rust-lang/compiler-team/blob/master/minutes/steering-meeting/2019.03.01.md + +## Out-of-tree crates +One of the primary goals of this policy is to ensure that there is consistency in how out-of-tree +crates used in the compiler are set up (at least, those maintained by the compiler team and living +in `rust-lang`) and that the experience is uniform across `rust-lang/rust` and these crates. + +### When should parts of the compiler be extracted into an out-of-tree crate? +This is left to the discretion of compiler team members but should be discussed with the rest of +the team, either through raising the question at the weekly triage meeting or asynchronously using +an FCP in an issue. If the crate is a product of a working group, there should already be agreement +within the working group that an out-of-tree crate is suitable. + +When considering creating an out-of-tree crate, it is worth balancing how general the crate should +be with the increased maintenance burden that this may bring if widely used. + +### Where should compiler crates live? +Out-of-tree compiler crates should be hosted in the `rust-lang` organization - this simplifies +integration with external infrastructure tooling and will inherit existing team permissions on +GitHub. It should be made clear in any documentation that the compiler team and any appropriate +working groups are responsible for the crate. It is not recommended to start with a prototype in +another organization or personal repository. + +### Can existing out-of-tree crates from personal accounts or other organizations be transferred? +Yes, this is encouraged. In order to do this, discuss this with the team and familiarize yourself +with [the GitHub documentation for repository transfers][repo_transfers] and then arrange to perform +the transfer. Once a transfer is complete, a redirect will exist in the original account or +organization and this will conflict with the names of any new forks of the transferred repository - +an email to GitHub is required to resolve this. + +[repo_transfers]: https://help.github.com/en/articles/transferring-a-repository + +### Who owns these crates? +It is desired that a compiler team member or working group has loose ownership over a crate so +that there are clear owners who are responsible for making sure that new versions are published and +that pull requests are reviewed. + +### What should these crates be named? +Crate naming will be discussed when new out-of-tree crates are proposed to the compiler team. + +Crate naming will differ on a case-by-case basis. Crates that are inherently tied to the +compiler would benefit from a name that is prefixed with `rustc_`. This is an indicator of how +stable the crate may be to prospective users. Other crates, which are more general-purpose, will +have names that are disentangled from the compiler. + +### Are there any limitations on the review policy for out-of-tree crates? +Generally, the working groups and team members that are primarily free to maintain the crate using +whatever practices are best suited to their group, however, there are some limitations so that there +is some uniformity across the compiler and out-of-tree crates: + +- Everyone with r+ on `rust-lang/rust` should be able to review and approve PRs. +- Where possible, only active participants in the crate (or related working group) need be on the + highfive rotation for the crate. +- It is fine to have additional reviewers on the crate who do not otherwise have r+ for Rust as a + whole, if those reviewers are actively involved in the working group or crate maintenance. +- Major pull requests should have multiple reviewers. + +### What is required of an out-of-tree crate? +It is required that out-of-tree crates must: + +- Be dual-licensed with Apache 2.0 and MIT when maintained by the compiler team (as the compiler + is) unless there is a compelling reason to do otherwise. + - If another license is desired, this must be brought up when proposing the new crate for + compiler team members to agree. Prefer [licenses accepted by tidy][licenses], unless otherwise + required (ports of code from other projects, etc). +- Abide by Rust's code of conduct. +- Specify that the crate is maintained by the Rust compiler team and any appropriate working groups. + - In particular, this should detail the expected level of maintenance and stability for any + prospective users. + - This should also link to the working group details in this repository. +- Be added to the list at the bottom of this page. +- Follow semantic versioning. +- Use `@bors` and `@rust-highfive`. +- Use labels that are compatible with the existing triage process. This will allow nominated issues + in your out-of-tree crate to be discussed during triage meetings. + - eg. `T-compiler`, `I-nominated` (a full list is to be decided) + +### Is there a requirement for community infrastructure for an out-of-tree crate? +There is no requirement that community infrastructure (such as Zulip servers/streams) be created for +out-of-tree crates. This may be desirable if an out-of-tree crate gains a large community of +contributors and users, but otherwise, the working group or compiler team streams should be used +initially. + +Linkifiers for auto-linking to issues and PRs on the primary Rust Zulip server can be added on +request. + +### Are there any recommendations for working with out-of-tree crates? +Recommendations for working with out-of-tree crates will be documented in the rustc-guide, see +[rust-lang/rustc-guide#285][guide_issue] for progress. + +[licenses]: https://github.com/rust-lang/rust/blob/master/src/tools/tidy/src/deps.rs#L10-L19 +[guide_issue]: https://github.com/rust-lang/rustc-guide/issues/285 + +--- + +In summary, the process for establishing an out-of-tree crate is as follows: + +1. Where appropriate, discuss and confirm the need within the working group for the out-of-tree + crate. +2. Create a PR modifying this document to include the crate in the list below. Use + [`@rfcbot merge`](https://github.com/anp/rfcbot-rs#usage) to gain agreement from compiler + team members. +3. Create a new repository in the `rust-lang` organization (permissions should be available for all + compiler team members). +4. Add a README describing the intended purpose of the crate, which team and working group are + responsible (link to their page in this repository) and the intended level of maintenance and + stability. + + > This crate is developed and maintained by the [Rust compiler team](..) for use within + > `rustc`, in particular, it is the responsibility of the + > [`.template`](../working-groups/.template) working group. This crate [will have regular + > breaking changes and provides no stability guarantees|is intended to remain stable and have + > limited breaking changes]. +5. Include the [LICENSE-APACHE][apache] and [LICENSE-MIT][mit] files from `rust-lang/rust`. +6. Include or link the [CODE_OF_CONDUCT][coc] file from `rust-lang/rust`. +7. Consult with the infrastructure team to set up `@bors` and `@rust-highfive` and a process for + publishing under the "The Rust Project Developers" crates.io account. +8. Perform any initial development required before integration with rustc. +9. Publish initial version, following semantic versioning. +10. Add the crate as a dependency to the appropriate in-tree crate and start using. + +[apache]: https://github.com/rust-lang/rust/blob/master/LICENSE-APACHE +[coc]: https://github.com/rust-lang/rust/blob/master/CODE_OF_CONDUCT.md +[mit]: https://github.com/rust-lang/rust/blob/master/LICENSE-MIT + +## Third-party crates +It is sometimes desirable to use the functionality of an existing third-party crate in the compiler. + +### When can a third-party crate be added as a compiler dependency? +It is desirable that a third-party crate being included in the compiler is well-maintained and that, +where possible, a compiler team member is added as a maintainer. You should consulting with the +rest of the compiler team before making this decision. + +### What about third-party dependencies to out-of-tree crates? +The same policies apply to all compiler-team-maintained crates used in the compiler. + +## List of out-of-tree crates +This section contains the list of existing out-of-tree, compiler team-maintained crates: + + - [`rust-lang-nursery/chalk`](https://github.com/rust-lang-nursery/chalk/) + - [`rust-lang-nursery/polonius`](https://github.com/rust-lang-nursery/polonius/)