From 6d1a6a89761e1c042d0c97f3535328b82fd85c4a Mon Sep 17 00:00:00 2001 From: David Wood Date: Fri, 1 Mar 2019 11:26:43 +0100 Subject: [PATCH 1/9] Add initial draft of crates policy. --- procedures/crates.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 procedures/crates.md diff --git a/procedures/crates.md b/procedures/crates.md new file mode 100644 index 00000000..d9e2ee3b --- /dev/null +++ b/procedures/crates.md @@ -0,0 +1,33 @@ +# Crate Policies +This document describe the guidelines for splitting the compiler up into crates and using +third-party crates in the compiler. These guidelines were originally discussed at the Rust All +Hands 2019 by the compiler team and others. + +## Where should compiler crates live? +As library-ification progresses and parts of the compiler are extracted into separate reusable +crates, these new crates should be hosted in the `rust-lang` organization. + +## Who owns these crates? +It is desired that a compiler team member has loose ownership over a crate so that there is someone +who is responsible for making sure that new versions are published and that pull requests are +reviewed. + +## What should these crates be named? +When naming a crate, it is worth considering that a `rustc_` prefix could result in +compiler-specific changes being made where this isn't appropriate as the crate was actually +intended to be general-purpose. + +## What should be included in a out-of-tree crate? +A maintenance policy should be included to set appropriate expectations for anyone who may wish to +use the crate. This enables killing dead code, and being able to make changes on a whim, where +appropriate, when this is required by a change in the compiler. + +Various other infrastructure should be put in place, such as `bors-ng` and `highfive`, to ensure +that the process is similar for in-tree and out-of-tree pull requests. Similarly, integration tests +should be run in CI and performance measured by `perf.rust-lang.org`. It may be worth consulting +with the infrastructure team to set these up. + +## Can I include a third-party crate? +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. It may be worth consulting with the +rest of the compiler team before making this decision. From 9d29fec7a2a5ad91971df5432b1ca5c34e9dbc71 Mon Sep 17 00:00:00 2001 From: David Wood Date: Sat, 2 Mar 2019 15:34:14 +0100 Subject: [PATCH 2/9] Add changes from steering meeting and review comments. --- procedures/crates.md | 163 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 132 insertions(+), 31 deletions(-) diff --git a/procedures/crates.md b/procedures/crates.md index d9e2ee3b..cf242cfe 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -1,33 +1,134 @@ -# Crate Policies -This document describe the guidelines for splitting the compiler up into crates and using -third-party crates in the compiler. These guidelines were originally discussed at the Rust All -Hands 2019 by the compiler team and others. - -## Where should compiler crates live? -As library-ification progresses and parts of the compiler are extracted into separate reusable -crates, these new crates should be hosted in the `rust-lang` organization. - -## Who owns these crates? -It is desired that a compiler team member has loose ownership over a crate so that there is someone -who is responsible for making sure that new versions are published and that pull requests are -reviewed. - -## What should these crates be named? -When naming a crate, it is worth considering that a `rustc_` prefix could result in -compiler-specific changes being made where this isn't appropriate as the crate was actually -intended to be general-purpose. - -## What should be included in a out-of-tree crate? -A maintenance policy should be included to set appropriate expectations for anyone who may wish to -use the crate. This enables killing dead code, and being able to make changes on a whim, where -appropriate, when this is required by a change in the compiler. - -Various other infrastructure should be put in place, such as `bors-ng` and `highfive`, to ensure -that the process is similar for in-tree and out-of-tree pull requests. Similarly, integration tests -should be run in CI and performance measured by `perf.rust-lang.org`. It may be worth consulting -with the infrastructure team to set these up. - -## Can I include a third-party crate? +# 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: + +- Every compiler team member must 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. +- Working group members (or regular contributors to the crate) who cannot approve PRs on rustc can + be allowed approve PRs to the crate. +- 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 (as the compiler is) unless otherwise + appropriate (ports of code from other project, 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`. + + +### 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. + +[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. Consult with the compiler team to confirm the need for the out-of-tree crate and kick-off the + naming bikeshed. +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. +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. It may be worth consulting with the +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/) From 9dc655f435f4f120ca42e56dc3c13e29b1310afd Mon Sep 17 00:00:00 2001 From: David Wood Date: Sat, 2 Mar 2019 15:40:22 +0100 Subject: [PATCH 3/9] Add small maintainance policy example. --- procedures/crates.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/procedures/crates.md b/procedures/crates.md index cf242cfe..b97e0d71 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -104,6 +104,12 @@ In summary, the process for establishing an out-of-tree crate is as follows: 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 From 8e4bdd7ec525aaae2bd2efa649c216bee9c515e0 Mon Sep 17 00:00:00 2001 From: David Wood Date: Wed, 6 Mar 2019 14:33:33 +0100 Subject: [PATCH 4/9] Fix typo in review policy limitations. --- procedures/crates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/procedures/crates.md b/procedures/crates.md index b97e0d71..3bda2841 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -58,7 +58,7 @@ is some uniformity across the compiler and out-of-tree crates: - Where possible, only active participants in the crate (or related working group) need be on the highfive rotation for the crate. - Working group members (or regular contributors to the crate) who cannot approve PRs on rustc can - be allowed approve PRs to the crate. + approve PRs to the crate. - Major pull requests should have multiple reviewers. ### What is required of an out-of-tree crate? From aa6795a00cf944573b22e4cf3598bbdf024de89c Mon Sep 17 00:00:00 2001 From: David Wood Date: Thu, 7 Mar 2019 23:27:04 +0100 Subject: [PATCH 5/9] Elaborate on acceptable licenses. --- procedures/crates.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/procedures/crates.md b/procedures/crates.md index 3bda2841..c4d64bb5 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -64,8 +64,9 @@ is some uniformity across the compiler and out-of-tree crates: ### 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 (as the compiler is) unless otherwise - appropriate (ports of code from other project, etc). +- Be dual-licensed with Apache 2.0 and MIT (as the compiler is) or + [any other license][licenses] accepted by tidy, unless otherwise appropriate (ports of code + from other project, 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 @@ -75,7 +76,6 @@ It is required that out-of-tree crates must: - Follow semantic versioning. - Use `@bors` and `@rust-highfive`. - ### 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 @@ -89,6 +89,7 @@ request. 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 --- From fce13c83df2ece11ce131ebb03d880bf76608292 Mon Sep 17 00:00:00 2001 From: David Wood Date: Sat, 9 Mar 2019 12:16:45 +0100 Subject: [PATCH 6/9] Strengthen license requirements, mention FCP and labels. --- procedures/crates.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/procedures/crates.md b/procedures/crates.md index c4d64bb5..3183487b 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -57,16 +57,18 @@ is some uniformity across the compiler and out-of-tree crates: - Every compiler team member must 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. -- Working group members (or regular contributors to the crate) who cannot approve PRs on rustc can - approve PRs to 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 (as the compiler is) or - [any other license][licenses] accepted by tidy, unless otherwise appropriate (ports of code - from other project, etc). +- 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 @@ -75,6 +77,9 @@ It is required that out-of-tree crates must: - 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 @@ -98,8 +103,8 @@ 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. Consult with the compiler team to confirm the need for the out-of-tree crate and kick-off the - naming bikeshed. +2. Create a PR modifying this document to include the PR in the list below. Use `@rfcbot fcp` 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 From e0869c4cbeab466fb3acf52ff73135e1e953d426 Mon Sep 17 00:00:00 2001 From: Mazdak Farrokhzad Date: Sat, 9 Mar 2019 11:56:32 +0000 Subject: [PATCH 7/9] Link to rfcbot usage. Co-Authored-By: davidtwco --- procedures/crates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/procedures/crates.md b/procedures/crates.md index 3183487b..30163dad 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -103,7 +103,7 @@ 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 PR in the list below. Use `@rfcbot fcp` to +2. Create a PR modifying this document to include the PR 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). From 741e07a262a3adbc106e46b096b2fc522bf5d17a Mon Sep 17 00:00:00 2001 From: David Wood Date: Tue, 12 Mar 2019 15:25:24 +0100 Subject: [PATCH 8/9] Clarify who should have r+. --- procedures/crates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/procedures/crates.md b/procedures/crates.md index 30163dad..0707663d 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -54,7 +54,7 @@ Generally, the working groups and team members that are primarily free to mainta 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: -- Every compiler team member must be able to review and approve PRs. +- 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 From b786e20724471dd73ca36c10e7b608f011cbbf33 Mon Sep 17 00:00:00 2001 From: David Wood Date: Tue, 12 Mar 2019 15:26:50 +0100 Subject: [PATCH 9/9] Correct typo. --- procedures/crates.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/procedures/crates.md b/procedures/crates.md index 0707663d..fe013515 100644 --- a/procedures/crates.md +++ b/procedures/crates.md @@ -103,8 +103,9 @@ 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 PR in the list below. Use [`@rfcbot merge`](https://github.com/anp/rfcbot-rs#usage) to - gain agreement from compiler team members. +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