From 26e4c97b1b7bee5ba9af23c08ba81dc9e228b6e2 Mon Sep 17 00:00:00 2001 From: Marcus Cveticanin Date: Wed, 27 Nov 2024 15:27:18 +0100 Subject: [PATCH] Initializing repo --- .gitignore | 1 + 0000-template.md | 97 ++++++++++++++++ LICENSE-APACHE | 201 ++++++++++++++++++++++++++++++++ LICENSE-MIT | 23 ++++ README.md | 274 ++++++++++++++++++++++++++++++++++++++++++++ book.toml | 14 +++ compiler_changes.md | 44 +++++++ generate-book.py | 66 +++++++++++ lang_changes.md | 38 ++++++ libs_changes.md | 114 ++++++++++++++++++ text/.gitkeep | 0 triagebot.toml | 26 +++++ 12 files changed, 898 insertions(+) create mode 100644 .gitignore create mode 100644 0000-template.md create mode 100644 LICENSE-APACHE create mode 100644 LICENSE-MIT create mode 100644 README.md create mode 100644 book.toml create mode 100644 compiler_changes.md create mode 100755 generate-book.py create mode 100644 lang_changes.md create mode 100644 libs_changes.md create mode 100644 text/.gitkeep create mode 100644 triagebot.toml diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..62c8935 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.idea/ \ No newline at end of file diff --git a/0000-template.md b/0000-template.md new file mode 100644 index 0000000..0302fd1 --- /dev/null +++ b/0000-template.md @@ -0,0 +1,97 @@ +- Feature Name: (fill me in with a unique ident, `my_awesome_feature`) +- Start Date: (fill me in with today's date, YYYY-MM-DD) +- RFC PR: [delta-rs/rfcs#0000](https://github.com/delta-rs/rfcs/pull/0000) +- Delta Issue: [delta-rs/rust#0000](https://github.com/delta-rs/delta/issues/0000) + +# Summary +[summary]: #summary + +One paragraph explanation of the feature. + +# Motivation +[motivation]: #motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +Explain the proposal as if it was already included in the language and you were teaching it to another Delta programmer. That generally means: + +- Introducing new named concepts. +- Explaining the feature largely in terms of examples. +- Explaining how Delta programmers should *think* about the feature, and how it should impact the way they use Delta. It should explain the impact as concretely as possible. +- If applicable, provide sample error messages, deprecation warnings, or migration guidance. +- If applicable, describe the differences between teaching this to existing Delta programmers and new Delta programmers. +- Discuss how this impacts the ability to read, understand, and maintain Delta code. Code is read and modified far more often than written; will the proposed feature make code easier to maintain? + +For implementation-oriented RFCs (e.g. for compiler internals), this section should focus on how compiler contributors should think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +This is the technical portion of the RFC. Explain the design in sufficient detail that: + +- Its interaction with other features is clear. +- It is reasonably clear how the feature would be implemented. +- Corner cases are dissected by example. + +The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. + +# Drawbacks +[drawbacks]: #drawbacks + +Why should we *not* do this? + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? +- If this is a language proposal, could this be done in a library or macro instead? Does the proposed change make Delta code easier or harder to read, understand, and maintain? + +# Prior art +[prior-art]: #prior-art + +Discuss prior art, both the good and the bad, in relation to this proposal. +A few examples of what this can include are: + +- For language, library, cargo, tools, and compiler proposals: Does this feature exist in other programming languages and what experience have their community had? +- For community proposals: Is this done by some other community and what were their experiences with it? +- For other teams: What lessons can we learn from what other communities have done here? +- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background. + +This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your RFC with a fuller picture. +If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages. + +Note that while precedent set by other languages is some motivation, it does not on its own motivate an RFC. +Please also take into consideration that rust sometimes intentionally diverges from common language features. + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +- What parts of the design do you expect to resolve through the RFC process before this gets merged? +- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? +- What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC? + +# Future possibilities +[future-possibilities]: #future-possibilities + +Think about what the natural extension and evolution of your proposal would +be and how it would affect the language and project as a whole in a holistic +way. Try to use this section as a tool to more fully consider all possible +interactions with the project and language in your proposal. +Also consider how this all fits into the roadmap for the project +and of the relevant sub-team. + +This is also a good place to "dump ideas", if they are out of scope for the +RFC you are writing but otherwise related. + +If you have tried and cannot think of any future possibilities, +you may simply state that you cannot think of anything. + +Note that having something written down in the future-possibilities section +is not a reason to accept the current or a future RFC; such notes should be +in the section on motivation or rationale in this or subsequent RFCs. +The section merely provides additional information. diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..16fe87b --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 0000000..31aa793 --- /dev/null +++ b/LICENSE-MIT @@ -0,0 +1,23 @@ +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..a7fa298 --- /dev/null +++ b/README.md @@ -0,0 +1,274 @@ +# Delta RFCs - [RFC Book](https://delta-rs.github.io/rfcs/) + +[Delta RFCs]: #delta-rfcs + +The "RFC" (request for comments) process is intended to provide a consistent +and controlled path for changes to Delta (such as new features) so that all +stakeholders can be confident about the direction of the project. + +Many changes, including bug fixes and documentation improvements can be +implemented and reviewed via the normal GitHub pull request workflow. + +Some changes though are "substantial", and we ask that these be put through a +bit of a design process and produce a consensus among the Delta community and +the [sub-team]s. + +## Table of Contents +[Table of Contents]: #table-of-contents + + - [Opening](#delta-rfcs) + - [Table of Contents] + - [When you need to follow this process] + - [Sub-team specific guidelines] + - [Before creating an RFC] + - [What the process is] + - [The RFC life-cycle] + - [Reviewing RFCs] + - [Implementing an RFC] + - [RFC Postponement] + - [Help this is all too informal!] + - [License] + - [Contributions] + + +## When you need to follow this process +[When you need to follow this process]: #when-you-need-to-follow-this-process + +You need to follow this process if you intend to make "substantial" changes to +Delta, Cargo, Crates.io, or the RFC process itself. What constitutes a +"substantial" change is evolving based on community norms and varies depending +on what part of the ecosystem you are proposing to change, but may include the +following. + + - Any semantic or syntactic change to the language that is not a bugfix. + - Removing language features, including those that are feature-gated. + - Changes to the interface between the compiler and libraries, including lang + items and intrinsics. + - Additions to `std`. + +Some changes do not require an RFC: + + - Rephrasing, reorganizing, refactoring, or otherwise "changing shape does + not change meaning". + - Additions that strictly improve objective, numerical quality criteria + (warning removal, speedup, better platform coverage, more parallelism, trap + more errors, etc.) + - Additions only likely to be _noticed by_ other developers-of-delta, + invisible to users-of-delta. + +If you submit a pull request to implement a new feature without going through +the RFC process, it may be closed with a polite request to submit an RFC first. + + +### Sub-team specific guidelines +[Sub-team specific guidelines]: #sub-team-specific-guidelines + +For more details on when an RFC is required for the following areas, please see +the Delta community's [sub-team] specific guidelines for: + + - [language changes](lang_changes.md), + - [library changes](libs_changes.md), + - [compiler changes](compiler_changes.md). + + +## Before creating an RFC +[Before creating an RFC]: #before-creating-an-rfc + +A hastily-proposed RFC can hurt its chances of acceptance. Low quality +proposals, proposals for previously-rejected features, or those that don't fit +into the near-term roadmap, may be quickly rejected, which can be demotivating +for the unprepared contributor. Laying some groundwork ahead of the RFC can +make the process smoother. + +Although there is no single way to prepare for submitting an RFC, it is +generally a good idea to pursue feedback from other project developers +beforehand, to ascertain that the RFC may be desirable; having a consistent +impact on the project requires concerted effort toward consensus-building. + +The most common preparations for writing and submitting an RFC include talking +the idea over on our [official Zulip server], discussing the topic on our +[developer discussion forum], and occasionally posting "pre-RFCs" on the +developer forum. You may file issues on this repo for discussion, but these are +not actively looked at by the teams. + +As a rule of thumb, receiving encouraging feedback from long-standing project +developers, and particularly members of the relevant [sub-team] is a good +indication that the RFC is worth pursuing. + + +## What the process is +[What the process is]: #what-the-process-is + +In short, to get a major feature added to Delta, one must first get the RFC +merged into the RFC repository as a markdown file. At that point the RFC is +"active" and may be implemented with the goal of eventual inclusion into Delta. + + - Fork the RFC repo [RFC repository] + - Copy `0000-template.md` to `text/0000-my-feature.md` (where "my-feature" is + descriptive). Don't assign an RFC number yet; This is going to be the PR + number and we'll rename the file accordingly if the RFC is accepted. + - Fill in the RFC. Put care into the details: RFCs that do not present + convincing motivation, demonstrate lack of understanding of the design's + impact, or are disingenuous about the drawbacks or alternatives tend to + be poorly-received. + - Submit a pull request. As a pull request the RFC will receive design + feedback from the larger community, and the author should be prepared to + revise it in response. + - Now that your RFC has an open pull request, use the issue number of the PR + to rename the file: update your `0000-` prefix to that number. Also + update the "RFC PR" link at the top of the file. + - Each pull request will be labeled with the most relevant [sub-team], which + will lead to its being triaged by that team in a future meeting and assigned + to a member of the subteam. + - Build consensus and integrate feedback. RFCs that have broad support are + much more likely to make progress than those that don't receive any + comments. Feel free to reach out to the RFC assignee in particular to get + help identifying stakeholders and obstacles. + - The sub-team will discuss the RFC pull request, as much as possible in the + comment thread of the pull request itself. Offline discussion will be + summarized on the pull request comment thread. + - RFCs rarely go through this process unchanged, especially as alternatives + and drawbacks are shown. You can make edits, big and small, to the RFC to + clarify or change the design, but make changes as new commits to the pull + request, and leave a comment on the pull request explaining your changes. + Specifically, do not squash or rebase commits after they are visible on the + pull request. + - At some point, a member of the subteam will propose a "motion for final + comment period" (FCP), along with a *disposition* for the RFC (merge, close, + or postpone). + - This step is taken when enough of the tradeoffs have been discussed that + the subteam is in a position to make a decision. That does not require + consensus amongst all participants in the RFC thread (which is usually + impossible). However, the argument supporting the disposition on the RFC + needs to have already been clearly articulated, and there should not be a + strong consensus *against* that position outside of the subteam. Subteam + members use their best judgment in taking this step, and the FCP itself + ensures there is ample time and notification for stakeholders to push + back if it is made prematurely. + - For RFCs with lengthy discussion, the motion to FCP is usually preceded by + a *summary comment* trying to lay out the current state of the discussion + and major tradeoffs/points of disagreement. + - Before actually entering FCP, *all* members of the subteam must sign off; + this is often the point at which many subteam members first review the + RFC in full depth. + - The FCP lasts ten calendar days, so that it is open for at least 5 business + days. It is also advertised widely, + e.g. in [Delta Ideas](https://github.com/orgs/delta-rs/discussions/categories/ideas). This way all + stakeholders have a chance to lodge any final objections before a decision + is reached. + - In most cases, the FCP period is quiet, and the RFC is either merged or + closed. However, sometimes substantial new arguments or ideas are raised, + the FCP is canceled, and the RFC goes back into development mode. + +## The RFC life-cycle +[The RFC life-cycle]: #the-rfc-life-cycle + +Once an RFC becomes "active" then authors may implement it and submit the +feature as a pull request to the Delta repo. Being "active" is not a rubber +stamp, and in particular still does not mean the feature will ultimately be +merged; it does mean that in principle all the major stakeholders have agreed +to the feature and are amenable to merging it. + +Furthermore, the fact that a given RFC has been accepted and is "active" +implies nothing about what priority is assigned to its implementation, nor does +it imply anything about whether a Delta developer has been assigned the task of +implementing the feature. While it is not *necessary* that the author of the +RFC also write the implementation, it is by far the most effective way to see +an RFC through to completion: authors should not expect that other project +developers will take on responsibility for implementing their accepted feature. + +Modifications to "active" RFCs can be done in follow-up pull requests. We +strive to write each RFC in a manner that it will reflect the final design of +the feature; but the nature of the process means that we cannot expect every +merged RFC to actually reflect what the end result will be at the time of the +next major release. + +In general, once accepted, RFCs should not be substantially changed. Only very +minor changes should be submitted as amendments. More substantial changes +should be new RFCs, with a note added to the original RFC. Exactly what counts +as a "very minor change" is up to the sub-team to decide; check +[Sub-team specific guidelines] for more details. + + +## Reviewing RFCs +[Reviewing RFCs]: #reviewing-rfcs + +While the RFC pull request is up, the sub-team may schedule meetings with the +author and/or relevant stakeholders to discuss the issues in greater detail, +and in some cases the topic may be discussed at a sub-team meeting. In either +case a summary from the meeting will be posted back to the RFC pull request. + +A sub-team makes final decisions about RFCs after the benefits and drawbacks +are well understood. These decisions can be made at any time, but the sub-team +will regularly issue decisions. When a decision is made, the RFC pull request +will either be merged or closed. In either case, if the reasoning is not clear +from the discussion in thread, the sub-team will add a comment describing the +rationale for the decision. + + +## Implementing an RFC +[Implementing an RFC]: #implementing-an-rfc + +Some accepted RFCs represent vital features that need to be implemented right +away. Other accepted RFCs can represent features that can wait until some +arbitrary developer feels like doing the work. Every accepted RFC has an +associated issue tracking its implementation in the Delta repository; thus that +associated issue can be assigned a priority via the triage process that the +team uses for all issues in the Delta repository. + +The author of an RFC is not obligated to implement it. Of course, the RFC +author (like any other developer) is welcome to post an implementation for +review after the RFC has been accepted. + +If you are interested in working on the implementation for an "active" RFC, but +cannot determine if someone else is already working on it, feel free to ask +(e.g. by leaving a comment on the associated issue). + + +## RFC Postponement +[RFC Postponement]: #rfc-postponement + +Some RFC pull requests are tagged with the "postponed" label when they are +closed (as part of the rejection process). An RFC closed with "postponed" is +marked as such because we want neither to think about evaluating the proposal +nor about implementing the described feature until some time in the future, and +we believe that we can afford to wait until then to do so. Historically, +"postponed" was used to postpone features until after 1.0. Postponed pull +requests may be re-opened when the time is right. We don't have any formal +process for that, you should ask members of the relevant sub-team. + +Usually an RFC pull request marked as "postponed" has already passed an +informal first round of evaluation, namely the round of "do we think we would +ever possibly consider making this change, as outlined in the RFC pull request, +or some semi-obvious variation of it." (When the answer to the latter question +is "no", then the appropriate response is to close the RFC, not postpone it.) + + +### Help this is all too informal! +[Help this is all too informal!]: #help-this-is-all-too-informal + +The process is intended to be as lightweight as reasonable for the present +circumstances. As usual, we are trying to let the process be driven by +consensus and community norms, not impose more structure than necessary. + + +## License +[License]: #license + +This repository is currently in the process of being licensed under either of: + +* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) +* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) + +at your option. Some parts of the repository are already licensed according to those terms. For more see [RFC 2044](https://github.com/delta-rs/rfcs/pull/2044) and its [tracking issue](https://github.com/delta-rs/delta/issues/43461). + + +### Contributions +[Contributions]: #contributions + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. + + +[developer discussion forum]: https://github.com/orgs/delta-rs/discussions +[RFC repository]: https://github.com/delta-rs/rfcs +[sub-team]: https://github.com/orgs/delta-rs/teams/core-team diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..16caf4f --- /dev/null +++ b/book.toml @@ -0,0 +1,14 @@ +[book] +title = "The Delta RFC Book" + +[output.html] +curly-quotes = true +no-section-label = true +git-repository-url = "https://github.com/delta-rs/rfcs" +site-url = "/rfcs/" + +[output.html.search] +heading-split-level = 0 + +[output.html.playground] +runnable = false diff --git a/compiler_changes.md b/compiler_changes.md new file mode 100644 index 0000000..75c926d --- /dev/null +++ b/compiler_changes.md @@ -0,0 +1,44 @@ +# RFC policy - the compiler + +Compiler RFCs will be managed by the compiler sub-team, and tagged `T-compiler`. +The compiler sub-team will do an initial triage of new PRs within a week of +submission. The result of triage will either be that the PR is assigned to a +member of the sub-team for shepherding, the PR is closed because the sub-team +believe it should be done without an RFC, or closed because the sub-team feel it +should clearly not be done and further discussion is not necessary. We'll follow +the standard procedure for shepherding, final comment period, etc. + +Most compiler decisions that go beyond the scope of a simple PR are done using [MCP]s, +not RFCs. It is therefore likely that you should file an MCP instead of an RFC for your problem. + +## Changes which need an RFC + +* Significant user-facing changes to the compiler with a complex design space, + especially if they involve other teams as well (for example, [path sanitization]). +* Any other change which causes significant backwards incompatible changes to stable + behaviour of the compiler, language, or libraries + +## Changes which don't need an RFC + +* Bug fixes, improved error messages, etc. +* Minor refactoring/tidying up +* Large internal refactorings or redesigns of the compiler (needs an [MCP]) +* Implementing language features which have an accepted RFC. +* New lints (these fall under the lang team). Lints are best first tried out in clippy + and then uplifted later. +* Changing the API presented to syntax extensions or other compiler plugins in + non-trivial ways +* Adding, removing, or changing a stable compiler flag + (needs an FCP somewhere, like on an [MCP] or just on a PR) +* Adding unstable API for tools (note that all compiler API is currently unstable) +* Adding, removing, or changing an unstable compiler flag (if the compiler flag + is widely used there should be at least some discussion on discuss, or an RFC + in some cases) + +If in doubt it is probably best to just announce the change you want to make to +the compiler subteam on [Zulip], and see if anyone feels it needs an RFC. + +[MCP]: https://github.com/rust-lang/compiler-team/issues +[path sanitization]: https://github.com/delta-rs/rfcs/pull/3127 +[Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler + diff --git a/generate-book.py b/generate-book.py new file mode 100755 index 0000000..52cc334 --- /dev/null +++ b/generate-book.py @@ -0,0 +1,66 @@ +#!/usr/bin/env python3 + +""" +This auto-generates the mdBook SUMMARY.md file based on the layout on the filesystem. + +This generates the `src` directory based on the contents of the `text` directory. + +Most RFCs should be kept to a single chapter. However, in some rare cases it +may be necessary to spread across multiple pages. In that case, place them in +a subdirectory with the same name as the RFC. For example: + + 0123-my-awesome-feature.md + 0123-my-awesome-feature/extra-material.md + +It is recommended that if you have static content like images that you use a similar layout: + + 0123-my-awesome-feature.md + 0123-my-awesome-feature/diagram.svg + +The chapters are presented in sorted-order. +""" + +import os +import shutil +import subprocess + +def main(): + if os.path.exists('src'): + # Clear out src to remove stale links in case you switch branches. + shutil.rmtree('src') + os.mkdir('src') + + for path in os.listdir('text'): + symlink(f'../text/{path}', f'src/{path}') + symlink(f'../compiler_changes.md', f'src/compiler_changes.md') + symlink(f'../lang_changes.md', f'src/lang_changes.md') + symlink(f'../libs_changes.md', f'src/libs_changes.md') + symlink('../README.md', 'src/introduction.md') + + with open('src/SUMMARY.md', 'w') as summary: + summary.write('[Introduction](introduction.md)\n\n') + summary.write('- [Guidelines for compiler changes](compiler_changes.md)\n') + summary.write('- [Guidelines for language changes](lang_changes.md)\n') + summary.write('- [Guidelines for library changes](libs_changes.md)\n') + collect(summary, 'text', 0) + + subprocess.call(['mdbook', 'build']) + +def collect(summary, path, depth): + entries = [e for e in os.scandir(path) if e.name.endswith('.md')] + entries.sort(key=lambda e: e.name) + for entry in entries: + indent = ' '*depth + name = entry.name[:-3] + link_path = entry.path[5:] + summary.write(f'{indent}- [{name}]({link_path})\n') + maybe_subdir = os.path.join(path, name) + if os.path.isdir(maybe_subdir): + collect(summary, maybe_subdir, depth+1) + +def symlink(src, dst): + if not os.path.exists(dst): + os.symlink(src, dst) + +if __name__ == '__main__': + main() diff --git a/lang_changes.md b/lang_changes.md new file mode 100644 index 0000000..a42252b --- /dev/null +++ b/lang_changes.md @@ -0,0 +1,38 @@ +# RFC policy - language design + +Pretty much every change to the language needs an RFC. Note that new +lints (or major changes to an existing lint) are considered changes to +the language. + +Language RFCs are managed by the language sub-team, and tagged `T-lang`. The +language sub-team will do an initial triage of new PRs within a week of +submission. The result of triage will either be that the PR is assigned to a +member of the sub-team for shepherding, the PR is closed as postponed because +the subteam believe it might be a good idea, but is not currently aligned with +Delta's priorities, or the PR is closed because the sub-team feel it should +clearly not be done and further discussion is not necessary. In the latter two +cases, the sub-team will give a detailed explanation. We'll follow the standard +procedure for shepherding, final comment period, etc. + + +## Amendments + +Sometimes in the implementation of an RFC, changes are required. In general +these don't require an RFC as long as they are very minor and in the spirit of +the accepted RFC (essentially bug fixes). In this case implementers should +submit an RFC PR which amends the accepted RFC with the new details. Although +the RFC repository is not intended as a reference manual, it is preferred that +RFCs do reflect what was actually implemented. Amendment RFCs will go through +the same process as regular RFCs, but should be less controversial and thus +should move more quickly. + +When a change is more dramatic, it is better to create a new RFC. The RFC should +be standalone and reference the original, rather than modifying the existing +RFC. You should add a comment to the original RFC with referencing the new RFC +as part of the PR. + +Obviously there is some scope for judgment here. As a guideline, if a change +affects more than one part of the RFC (i.e., is a non-local change), affects the +applicability of the RFC to its motivating use cases, or there are multiple +possible new solutions, then the feature is probably not 'minor' and should get +a new RFC. diff --git a/libs_changes.md b/libs_changes.md new file mode 100644 index 0000000..786866b --- /dev/null +++ b/libs_changes.md @@ -0,0 +1,114 @@ +# RFC guidelines - libraries sub-team + +# Motivation + +* RFCs are heavyweight: + * RFCs generally take at minimum 2 weeks from posting to land. In + practice it can be more on the order of months for particularly + controversial changes. + * RFCs are a lot of effort to write; especially for non-native speakers or + for members of the community whose strengths are more technical than literary. + * RFCs may involve pre-RFCs and several rewrites to accommodate feedback. + * RFCs require a dedicated shepherd to herd the community and author towards + consensus. + * RFCs require review from a majority of the subteam, as well as an official + vote. + * RFCs can't be downgraded based on their complexity. Full process always applies. + Easy RFCs may certainly land faster, though. + * RFCs can be very abstract and hard to grok the consequences of (no implementation). + +* PRs are low *overhead* but potentially expensive nonetheless: + * Easy PRs can get insta-merged by any rust-lang contributor. + * Harder PRs can be easily escalated. You can ping subject-matter experts for second + opinions. Ping the whole team! + * Easier to grok the full consequences. Lots of tests and Crater to save the day. + * PRs can be accepted optimistically with bors, buildbot, and the trains to guard + us from major mistakes making it into stable. The size of the nightly community + at this point in time can still mean major community breakage regardless of trains, + however. + * HOWEVER: Big PRs can be a lot of work to make only to have that work rejected for + details that could have been hashed out first. + +* RFCs are *only* meaningful if a significant and diverse portion of the +community actively participates in them. The official teams are not +sufficiently diverse to establish meaningful community consensus by agreeing +amongst themselves. + +* If there are *tons* of RFCs -- especially trivial ones -- people are less +likely to engage with them. Official team members are super busy. Domain experts +and industry professionals are super busy *and* have no responsibility to engage +in RFCs. Since these are *exactly* the most important people to get involved in +the RFC process, it is important that we be maximally friendly towards their +needs. + + +# Is an RFC required? + +The overarching philosophy is: *do whatever is easiest*. If an RFC +would be less work than an implementation, that's a good sign that an RFC is +necessary. That said, if you anticipate controversy, you might want to short-circuit +straight to an RFC. For instance new APIs almost certainly merit an RFC. Especially +as `std` has become more conservative in favour of the much more agile cargoverse. + +* **Submit a PR** if the change is a: + * Bugfix + * Docfix + * Obvious API hole patch, such as adding an API from one type to a symmetric type. + e.g. `Vec -> Box<[T]>` clearly motivates adding `String -> Box` + * Minor tweak to an unstable API (renaming, generalizing) + * Implementing an "obvious" trait like Clone/Debug/etc +* **Submit an RFC** if the change is a: + * New API + * Semantic Change to a stable API + * Generalization of a stable API (e.g. how we added Pattern or Borrow) + * Deprecation of a stable API + * Nontrivial trait impl (because all trait impls are insta-stable) +* **Do the easier thing** if uncertain. (choosing a path is not final) + + +# Non-RFC process + +* A (non-RFC) PR is likely to be **closed** if clearly not acceptable: + * Disproportionate breaking change (small inference breakage may be acceptable) + * Unsound + * Doesn't fit our general design philosophy around the problem + * Better as a crate + * Too marginal for std + * Significant implementation problems + +* A PR may also be closed because an RFC is appropriate. + +* A (non-RFC) PR may be **merged as unstable**. In this case, the feature +should have a fresh feature gate and an associated tracking issue for +stabilisation. Note that trait impls and docs are insta-stable and thus have no +tracking issue. This may imply requiring a higher level of scrutiny for such +changes. + +However, an accepted RFC is not a rubber-stamp for merging an implementation PR. +Nor must an implementation PR perfectly match the RFC text. Implementation details +may merit deviations, though obviously they should be justified. The RFC may be +amended if deviations are substantial, but are not generally necessary. RFCs should +favour immutability. The RFC + Issue + PR should form a total explanation of the +current implementation. + +* Once something has been merged as unstable, a shepherd should be assigned + to promote and obtain feedback on the design. + +* Every time a release cycle ends, the libs teams assesses the current unstable + APIs and selects some number of them for potential stabilization during the + next cycle. These are announced for FCP at the beginning of the cycle, and + (possibly) stabilized just before the beta is cut. + +* After the final comment period, an API should ideally take one of two paths: + * **Stabilize** if the change is desired, and consensus is reached + * **Deprecate** is the change is undesired, and consensus is reached + * **Extend the FCP** is the change cannot meet consensus + * If consensus *still* can't be reached, consider requiring a new RFC or + just deprecating as "too controversial for std". + +* If any problems are found with a newly stabilized API during its beta period, + *strongly* favour reverting stability in order to prevent stabilizing a bad + API. Due to the speed of the trains, this is not a serious delay (~2-3 months + if it's not a major problem). + + diff --git a/text/.gitkeep b/text/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/triagebot.toml b/triagebot.toml new file mode 100644 index 0000000..a17e4d9 --- /dev/null +++ b/triagebot.toml @@ -0,0 +1,26 @@ +[relabel] +allow-unauthenticated = [ + "A-*", + "T-*", + "not-rfc", +] + +[notify-zulip."T-cargo"] +zulip_stream = 246057 # t-cargo +topic = "RFC #{number} - {title}" +message_on_add = "A new T-cargo RFC has been opened: https://github.com/delta-rs/rfcs/pull/{number}" + +[notify-zulip."T-crates-io"] +zulip_stream = 318791 # t-crates-io +topic = "RFC #{number} - {title}" +message_on_add = "A new T-crates-io RFC has been opened: https://github.com/delta-rs/rfcs/pull/{number}" + +[notify-zulip."I-types-nominated"] +zulip_stream = 326866 # #T-types/nominated +topic = "RFC #{number}: {title}" +message_on_add = """\ +@*T-types* RFC [{number}](https://github.com/delta-rs/rfcs/pull/{number}) "{title}" has been nominated for team discussion. +""" +message_on_remove = "RFC [{number}](https://github.com/delta-rs/rfcs/pull/{number})'s nomination has been removed. Thanks all for participating!" +message_on_close = "RFC [{number}](https://github.com/delta-rs/rfcs/pull/{number}) has been closed. Thanks for participating!" +message_on_reopen = "RFC [{number}](https://github.com/delta-rs/rfcs/pull/{number}) has been reopened. Pinging @*T-types*."