diff --git a/process.md b/process.md index 3408e2d567..c5a89a8fa3 100644 --- a/process.md +++ b/process.md @@ -1,28 +1,16 @@ # Swift Evolution Process -Swift is a powerful and intuitive programming language that is designed to make writing and maintaining correct programs easier. Swift is growing and evolving, guided by a community-driven process referred to as the Swift evolution process, maintained by the [Language Steering Group][language-steering-group]. This document outlines the Swift evolution process and how a feature grows from a rough idea into something that can improve the Swift development experience for millions of programmers. +Swift is a powerful and intuitive programming language that is designed to make writing and maintaining correct programs easier. Swift is growing and evolving, guided by a community-driven process referred to as the Swift evolution process. This document outlines the Swift evolution process and how a feature grows from a rough idea into something that can improve the Swift development experience for millions of programmers. ## Scope -The Swift evolution process covers all design changes, no matter how small, to the Swift language, its standard library, and the core tools necessary to build Swift programs. This includes additions, removals, and changes to: +The Swift evolution process applies to all design changes to specific aspects of the Swift project. This includes the Swift language, its standard library and certain other core libraries, and the interfaces of core tools such as the Swift package manager. The complete list is given [below](#evolution-areas). -- the features of the Swift language, -- the public interface of the Swift standard library, -- the configuration of the Swift compiler, -- the core tools of the Swift package ecosystem, including the configuration of - the [Swift package manager](https://www.swift.org/package-manager/) and the - design of its manifest files, and -- the public interfaces of the following libraries: - - [Swift Testing](https://github.com/swiftlang/swift-testing) - - [XCTest](https://github.com/swiftlang/swift-corelibs-xctest) - -The design of other tools, such as IDEs, debuggers, and documentation generators, is not covered by the evolution process. The Core Team may create workgroups to guide and make recommendations about the development of these tools, but the output of those workgroups is not reviewed. +The evolution process applies only to the design of features, not their implementation. Implementation work in the Swift project is generally open-source and subject to the normal code review process; see [Contributing to Swift](https://www.swift.org/contributing/). Changes such as bug fixes, optimizations, and diagnostic improvements can be contributed at any time. Implementation review is generally completely independent from the design review performed by the Swift evolution process. However, there is one important exception: patches that would change a design covered by the evolution process should not be merged without the approval of the appropriate evolution workgroup. This may include fixing bugs, if the bug allows additional things to be expressed or changes the user-visible behavior of a feature. Bugs in features that have not yet been officially released can be freely fixed. Implementors should check with the appropriate evolution workgroup if they're uncertain what to do. -The evolution process does not cover experimental features, which can be added, changed, or removed at any time. Implementors should take steps to prevent the accidental use of experimental features, such as by enabling them only under explicitly experimental options. Features should not be allowed to remain perpetually experimental; a feature with no clear path for development into an official feature should be removed. +The evolution process does not cover the design of experimental features, which can be added, changed, or removed at any time using the normal code review process. Implementations should take steps to prevent the accidental use of experimental features, such as by enabling them only when an explicitly experimental command line flag is passed to the tool. Features should not be allowed to remain perpetually experimental; a feature with no clear path for development into an official feature should be removed. -Changes such as bug fixes, optimizations, or diagnostic improvements can be contributed via the normal contribution process; see [Contributing to Swift](https://www.swift.org/contributing/). Some bug fixes are effectively substantial changes to the design, even if they're just making the implementation match the official documentation; whether such a change requires evolution review is up to the appropriate evolution workgroup. - -Which parts of the Swift project are covered by the evolution process is ultimately up to the judgment of the Core Team. +The evolution process does not cover everything that is important for writing Swift code. The design of tools such as IDEs, debuggers, profilers, and documentation generators is outside of the scope of the evolution process. The Core Team may empower workgroups to guide or offer recommendations for the development of these tools, but that guidance is not reviewed, and recommendations for tools developed outside of the Swift project are not binding. ## Goals @@ -33,161 +21,186 @@ The Swift evolution process aims to leverage the collective ideas, insights, and There is a natural tension between these two goals. Open evolution processes are, by nature, chaotic. Yet, maintaining a coherent vision for something as complicated as a programming language requires some level of coordination. The Swift evolution process aims to strike a balance that best serves the Swift community as a whole. -## Community structure +## Evolution workgroups + +The [Core Team](https://www.swift.org/community/#core-team) is responsible for the strategic direction of Swift. As part of this, it identifies areas of the Swift project that should be covered by the evolution process. Anything not so identified is not covered by the evolution process. + +The Core Team may elect to delegate evolution authority over a specific area to a particular [steering group or workgroup](https://www.swift.org/community/). Otherwise, that evolution authority remains with the Core Team. The group that exercises evolution authority over an area is called its *evolution workgroup*. The Core Team's delegation of authority is not absolute, and it retains the right to override individual decisions as it sees fit. + +Evolution workgroups are responsible for deciding the details of how the evolution process applies to its evolution area, within the guidelines laid out in the following section. If a proposal touches on multiple evolution areas, all affected evolution workgroups work together to decide and carry out the details of the evolution process for the proposal. + +## Evolution review + +The evolution process normally consists of two key steps: + +1. the creation of a *proposal document* that describes the proposal, which is usually developed and discussed in a [forums thread][forums] called a *pitch*; and + +2. an *open review* of the proposal by the community at large, after which the evolution workgroup decides what to do with it. + +A proposal that has gone through these two steps and been accepted by the evolution workgroup is said to have undergone review. Every substantial design change in an area covered by the evolution process must undergo review. An evolution workgroup may also decide to reject or, for minor proposals, accept a change without it undergoing review; these cases will be described in more detail [at the end of this section](#summary-acceptance-and-rejection). + +The exact details of the review process for a specific evolution area are decided by the appropriate evolution workgroup and documented in the [Evolution Areas](#evolution-areas) section of this document. In general, though, it looks like one of two basic processes: + +Most evolution areas use *full evolution review*. In this process, the pitch and open review are separate and explicit steps. The proposal is developed in a pitch thread until the author is satisfied with it and the workgroup believes it is ready for review. The workgroup then creates a new thread for the open review of that specific version of the proposal. After the review is complete, the workgroup either decides to accept it, reject it, or ask for revisions. If the proposal is revised in a substantially new way that has not been adequately discussed, the revised proposal must then undergo another round of open review. This may continue until the workgroup is ready to make a final decision. + +Some kinds of proposals instead use *lightweight evolution review*, which is significantly less formal. In the lightweight process, the pitch and open review steps are combined; there's no specifically-scheduled open review period. The proposal author creates a thread to discuss their proposal, and community members just offer their feedback in an open discussion there. If the author wants to revise their proposal, they just do so and inform the thread what they changed. Evolution workgroup members participate in that discussion normally. When the workgroup decides that the discussion has reached a logical conclusion and they're ready to make a final decision, they either accept or reject the proposal. + +The extra structure of full evolution review gives the Swift community much greater awareness of the proposal and a better opportunity to read, consider, and provide feedback on it. The core parts of the Swift project use full evolution review for all subtantial proposals. Lightweight evolution review is generally only appropriate for proposals with relatively low stakes for most Swift users. This might cover something like creating or organizing compiler diagnostic groups, or changes to the public API of a package that's not distributed as part of Swift releases. Workgroups should get the approval of their steering group or the Core Team before using lightweight evolution review for proposals. + +Whether an evolution area uses full or lightweight evolution review is documented in the [Evolution Areas](#evolution-areas) section of this document. + +### Summary acceptance and rejection + +Evolution workgroups may decide that certain design changes are sufficiently obvious to accept without a proposal document or open review. This is generally only appropriate for small adjustments to recently-accepted proposals where the workgroup feels that there is no reasonable objection or alternative to the proposed change. Examples include: + +- adding a method to a particular type which was overlooked in a proposal that added that method to several similar types; + +- forbidding an unsafe or nonsensical use of a new feature; or + +- gating a change behind an upcoming feature flag after it was discovered to cause significant source-compatibility problems. + +Such changes should still generally be announced in the release notes when they are made. Evolution workgroups should be circumspect about approving changes this way, and in close cases, they should err on the side of conducting a normal review. + +Evolution workgroups may also reject proposals without review if the workgroup believes that there's no possibility that further development or review of the proposal would lead to it being accepted. This should only be done when there's consensus within the workgroup, but it can be appropriate if, for example, the workgroup feels that the proposal is simply out of keeping with its overall design direction for the evolution area. The workgroup should clearly communicate its decision and the reasons why in any threads discussing the proposal. -The [Core Team](https://www.swift.org/community/#core-team) is responsible for the strategic direction of Swift. The Core Team creates workgroups focused on specific parts of the project. When the Core Team gives a workgroup authority over part of the evolution of the project, that workgroup is called an evolution workgroup. Evolution workgroups manage the evolution process for proposals under their authority, working together with other workgroups as needed. +## Participation + +Everyone in the Swift community is welcome to propose, discuss, and review ideas in any evolution area. + +### Reviewing a proposal + +You can provide feedback on a proposal in either the pitch phase or open review. If you have limited time to participate in Swift evolution, you should focus on reading and providing feedback on proposals during their open review. + +To participate in proposal review, you watch for proposal review threads in the appropriate section of the [forums][]. You should make an effort to read and understand the proposal document before providing feedback, but you do not have to read the review thread. The evolution workgroup may provide specific guidance about what they're looking for in review feedback, but in general, good feedback includes things like: + + - asking for clarification about what the document is trying to say + - evaluations of specific aspects of the proposal, rather than just broad sentiments + - examples of how you'd actually use the proposed change / how you don't think you'd be able to use it + +You can leave review feedback either publicly, by making a reply in the review thread, or privately, by sending a message directly to the review manager as laid out in the initial post of the review thread. If you leave feedback publicly, other community members may respond to you, but you are not obliged to engage with them; it's fine to leave your feedback and move on. In either case, the review manager may ask you for clarification so that they can more accurately represent your opinion to the rest of the workgroup. + +Please understand that open review is not a vote. The evolution workgroup is going to make a decision using its judgment of what's best for the project based on the information it has available to it. Simple statements of being for or against a proposal doesn't typically add much to the conversation. In contrast, a detailed argument that you don't think you'll be able to use the proposal because of a specific technical flaw is much more likely to be convincing. + +To participate in the pitch phase, you watch for pitch threads in the appropriate section of the [forums][]. Pitch discussions are usually informal, open-ended discussions about the problem at hand and how the author is trying to solve it. Participating in a pitch thread can be a very powerful way of shaping the idea before it ever proceeds to review, but it can also require a much more substantial time commitment. Good pitch feedback includes anything that would be appropriate as review feedback (above), plus: + + - evaluations of alternative approaches that you've used + - suggestions for how to improve the proposal document (if the author's started writing one) + +### Making a proposal + +The exact details of making a proposal may vary between evolution areas; read the [descriptions of the different areas](#evolution-areas) for more information. -Currently, there are three evolution workgroups: +1. You should start by checking to see if your idea's already being discussed. The [Swift forums][forums] have a search function that you can use to look for existing threads. Some evolution areas also maintain a list of commonly rejected proposals, which you can find linked from the appropriate section of this document. If the idea has come up before, but it hasn't been rejected, the discussion died down a long time ago, and you think you have something new to add, you are welcome to start a new pitch. -* The [Language Steering Group][language-steering-group] has authority over the evolution of the Swift language, its standard library, and any language configuration features of the Swift package manager. -* The [Platform Steering Group][platform-steering-group] has authority over the evolution of all other features of the Swift package manager and its manifest files. -* The [Testing Workgroup][testing-workgroup] has authority over the evolution of - the Swift Testing and Corelibs XCTest projects. +2. You *pitch* an idea by creating a thread to discuss it in a specific section of the forums. This is usually an informal, open-ended discussion about the problem you're trying to solve and your ideas about how to solve it. You do not need to have written a formal proposal at this point. If your search found any relevant prior threads, please link to them in your new pitch. -The Core Team manages (or delegates) the evolution process for proposals outside these areas. The Core Team also retains the power to override the evolution decisions of workgroups when necessary. +3. When you've developed a solid idea of what you want to propose, you write a formal *proposal document*. You should follow the appropriate template document for the evolution area you're working in. The template may describe additional requirements, like having a prototype implementation ready; this varies from area to area. Be sure to update the pitch thread whenever you make significant changes to the proposal. + +4. You signal that you think your proposal is ready for review by creating a non-[draft][draft-pr] pull request to add it to the appropriate directory in the [evolution repository][swift-evolution-repo]. + +5. In the full evolution process, the evolution workgroup will appoint a *review manager* to oversee your proposal. The review manager should get in touch within a few weeks to relay any additional feedback from the workgroup. When they agree that your proposal is ready, they'll create a dedicated thread for the open review in the appropriate section of the forums. This thread will be kept open for a period of at least ten days, covering at minimum two consecutive weekends. If you need to make revisions to your proposal during the review, the review period may need to be extended to give adequate review time to the change. + +6. In the lightweight evolution process, the open review is less formal and just continues in the original thread. You can make changes to the proposal document whenever you want as long as you update the thread. The review ends when the evolution workgroup decides that the discussion has reached a conclusion. + +7. After the review period ends, the evolution workgroup will decide what to do with your proposal. Possible outcomes include accepting it, outright rejecting it, or asking you to revise it, with the expectation of putting the revised proposal through another round of pitch or review. In the lightweight process, requests for changes will just be made as comments in the discussion thread, keeping the conversation alive. + +As a proposal author, you have a responsibility to try to respond to questions during the pitch and open review. Especially during the pitch phase, keep in mind that questions about your proposal often identify places where you can improve your proposal document to be clearer. + +You should also try to engage with feedback and make an effort to understand other people's criticisms. If they've identified a real flaw, you should thank them and revise the proposal accordingly. If they're misunderstanding your proposal, you can probably improve the document to clarify the point of confusion. If, after a reasonable discussion, you find that you simply disagree with them about the design, that's okay. Your objective should be to make the best case for your proposal that you can, both to the community at large and to the evolution workgroup. If the workgroup agrees with your side of the argument, they will accept your proposal even if you haven't achieved perfect consensus in the community. You may find it helpful, however, to write up the disagreement in the proposal document, perhaps as part of the motivation or in the Alternatives Considered section. + +Ultimately, open review is not a vote. The role of evolution reviewers is to provide feedback on the proposal, including arguments for or against it. The evolution workgroup will then consider these arguments and decide what is best for the Swift project. Neither the raw number of people making arguments on either side, nor the ferocity of their arguments, is a meaningful input to that decision. ## Proposals, roadmaps, and visions There are three kinds of documents commonly used in the evolution process. -* An evolution *proposal* describes a specific proposed change in detail. All evolution changes are advanced as proposals which will be discussed in the community and given a formal open review. +* An evolution *proposal* describes a specific proposed change in detail. All substantial design changes are advanced as proposals which will be discussed in the community and given a formal open review. * An evolution *roadmap* describes a concrete plan for how a complex change will be broken into separate proposals that can be individually pitched and reviewed. Considering large changes in small pieces allows the community to provide more focused feedback about each part of the change. A roadmap makes this organization easier for community members to understand. Roadmaps are planning documents that do not need to be reviewed. -* An evolution *vision* describes a high-level design for a broad topic (for example, string processing or concurrency). A vision creates a baseline of understanding in the community for future conversations on that topic, setting goals and laying out a possible program of work. +* An evolution *vision* describes a high-level design for a broad topic (for example, string processing or concurrency). A vision creates a baseline of understanding in the community for future conversations on that topic, setting goals and laying out a possible program of work. - Visions must be approved by the appropriate evolution workgroup. This approval is an endorsement of the vision's basic ideas, but not of any of its concrete proposals, which must still be separately developed and reviewed. + Visions must be approved by the appropriate evolution workgroup. This approval is an endorsement of the vision's basic ideas, but not of any of its concrete proposals, which must still be separately developed and reviewed. -## Participation +## Evolution areas -Everyone is welcome to propose, discuss, and review ideas to improve -the Swift language and standard library in the -[Evolution section of the Swift forums](https://forums.swift.org/c/evolution). -Before posting a review, please see the section "What goes into a review?" below. +### Language and standard library evolution -## What goes into a review? +The [Language Steering Group][language-steering-group] has authority over: +- the features of the Swift language, +- the public interface of the Swift standard library, +- the language configuration options of the Swift compiler, and +- the language configuration options of [Swift package manager][spm] manifest files. -The goal of the review process is to improve the proposal under review -through constructive criticism and, eventually, determine the -direction of Swift. When writing your review, here are some questions -you might want to answer in your review: +Language and standard library proposals use full evolution review. They are pitched in the [Evolution > Pitches][forum-pitches] section of the Swift forums and reviewed in the [Evolution > Proposal Reviews][forums-reviews] section. -* What is your evaluation of the proposal? -* Is the problem being addressed significant enough to warrant a change to Swift? -* Does this proposal fit well with the feel and direction of Swift? -* If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those? -* How much effort did you put into your review? A glance, a quick reading, or an in-depth study? +The LSG requires language and standard library proposals to have a prototype implementation before they can be reviewed. This implementation doesn't have to be fully professional and ready to release, but it at least has to be a viable proof of concept and in a state that can be used by reviewers. -Please state explicitly whether you believe that the proposal should be accepted into Swift. +Language and standard library proposal documents should use the [Swift proposal template](proposal-templates/0000-swift-template.md). They use the "SE" prefix and can be found in the [`proposals` directory](proposals/) of the Swift evolution repository. -## How to propose a change +The LSG maintains a list of [commonly rejected proposals](commonly_proposed.md). -1. **Check prior proposals** +### Package manager evolution - Many ideas come up frequently, and may either be in active discussion on the forums, or may have been discussed already and have joined the [Commonly Rejected Proposals](commonly_proposed.md) list. Please [search the forums](https://forums.swift.org/search) for context before proposing something new. +The [Ecosystem Steering Group][ecosystem-steering-group] has authority over all aspects of the [Swift package manager][spm] and its manifest files except language configuration. -1. **Consider the goals of the upcoming Swift release** +Package manager proposals use full evolution review. Proposals are pitched in the [Evolution > Pitches][forum-pitches] section of the Swift forums and reviewed in the [Evolution > Proposal Reviews][forums-reviews] section. - Each major Swift release is focused on a [specific set of goals](README.md) - described early in the release cycle. When proposing a change to - Swift, please consider how your proposal fits in with the larger goals - of the upcoming Swift release. Proposals that are clearly out of scope - for the upcoming Swift release will not be brought up for review. If you can't resist discussing a proposal that you know is out of scope, please include the tag `[Out of scope]` in the subject. +Package manager proposal documents should be based on the [package manager proposal template](proposal-templates/0000-swiftpm-template.md). For historical reasons, they also use the "SE" prefix and can be bound in the [`proposals` directory](proposals/) of the Swift evolution repository. -1. **Socialize the idea** +### Testing evolution - Propose a rough sketch of the idea in the ["pitches" section of the Swift forums](https://forums.swift.org/c/evolution/pitches), the problems it solves, what the solution looks like, etc., to gauge interest from the community. +The [Testing Workgroup][testing-workgroup] has authority over the evolution of the [Swift Testing](https://github.com/swiftlang/swift-testing) and [Corelibs XCTest](https://github.com/swiftlang/swift-corelibs-xctest) projects. -1. **Develop the proposal and implementation** +Testing proposals use full evolution review. They are pitched in the [Evolution > Pitches][forum-pitches] section of the Swift forums and reviewed in the [Evolution > Proposal Reviews][forums-reviews] section. - 1. Expand the rough sketch into a formal proposal using the - [relevant proposal template](#proposal-templates). - 1. In the [swift-evolution repository][swift-evolution-repo], open a - [draft pull request][draft-pr] that adds your proposal to the appropriate - [proposal directory](#proposal-locations). - 1. Announce the pull request on the forums and edit the root post to link out to the pull request. - 1. Refine the formal proposal in the open as you receive further feedback on the forums or the pull request. - A ripe proposal is expected to address commentary from present and past - discussions of the idea. +Testing proposals should use the [testing proposal template](proposal-templates/0000-swift-testing-template.md). They use the "ST" prefix and can be found in the [`proposals/testing` directory](proposals/testing/) of the Swift evolution repository. - Meanwhile, start working on an implementation. - Prototyping an implementation and its uses *alongside* the formal proposal - is important because it helps to determine an adequate scope, ensure - technical feasibility, and validate that the proposal lives up to - its motivation. +## Focus areas for Swift releases - A pull request with a working implementation is *required* for the - proposal to be accepted for review. - Proposals that can ship as part of the [Standard Library Preview package][preview-package] - should be paired with a pull request against the [swift-evolution-staging repository][swift-evolution-staging]. - All other proposals should be paired with an implementation pull request - against the [main Swift repository](https://github.com/swiftlang/swift). +Each major Swift release is focused on a [specific set of goals](README.md) described early in the release cycle. These focus areas don't necessarily mean that unrelated proposals won't be considered, but if the evolution workgroup decides that your proposal doesn't fit with the focus areas of the current release, they may ask you to hold it until a later release. - The preview package can accept new types, new protocols, and extensions to - existing types and protocols that can be implemented without access to - standard library internals or other non-public features. - For more information about the kinds of changes that can be implemented in - the preview package, see [SE-0264](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0264-stdlib-preview-package.md). +If you are worried that an idea might out of scope for the current release, please contact a representative of the appropriate evolution workgroup for guidance. -1. **Request a review** +
+Information mostly of interest to evolution workgroups - Once you have a working implementation and believe the proposal is sufficiently detailed and clear, mark the draft pull request in the [swift-evolution repository][swift-evolution-repo] as ready for review to indicate to the appropriate evolution workgroup that you would like the proposal to be reviewed. +## Proposal documents -> [!IMPORTANT] -> In general, and especially [during the review period](#review-process), be responsive to questions and feedback about the proposal. +Proposal documents should generally not be renamed once they've been added to the repository. It's okay to change the name of the proposal in the text, but the filename should remain stable. -[draft-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests +To simplify automated "scraping" of proposal documents, all proposal documents (and therefore proposal templates) should start with the following basic structure and use standard fields: + +```text +# Name of proposal + +* Field1: value +* Field2: value + +The remainder of the document has no specific requirements. +``` + +Standard fields include: + +* `Proposal`: exactly `[prefix-number](filename.md)`, where `prefix` is the appropriate document prefix (such as `SE` for language and SPM proposals), `number` is the sequence number of this proposal within that prefix, and `filename.md` is the filename of this proposal document. Required in all proposal documents. +* `Author` or `Authors`: a comma-separated list of authors. Required in all proposal documents. Usually, author names will link to their github profiles, but that is not required. The plural name `Authors` should be used if and only if there are multiple authors in the list. Authors should only list other people as co-authors with their explicit consent. +* `Review Manager` or `Review Managers`: a comma-separated list of review managers. Required in all proposal documents that use full evolution review. Usually, these will be links to their github profiles, but that is not required. The plural name `Review Managers` should be used if and only if there are multiple review managers in the list. +* `Status`: one of the [proposal states](#proposal-states), bolded using `**`. Required in all proposal documents. +* `Vision`: a link to a vision document which encompasses this proposal. Optional. +* `Roadmap`: a link to a roadmap document or thread which encompasses this proposal. Optional. +* `Bug`: a link to a bug related to this proposal. Optional. +* `Implementation`: a comma-separated list of links to implementation pull requests for this proposal. Optional. +* `Previous Proposal`: a link to a previous proposal (with a different document number) addressing the same idea. This field is rare because proposals are usually revised rather than replaced. Optional. +* `Previous Revision` or `Previous Revisions`: a space-separated list of permalinks to previous revisions of this proposal document. Optional. The link text should be a number, starting with 1. Only "official" revisions need to be listed, such as those used for different open reviews. The plural name `Previous Revisions` should be used if and only if there are multiple revisions in the list. Usually, there will be a previous revision for each additional review in the `Review` field, but sometimes multiple reviews are conducted on the same text in order to focus on different aspects of the proposal. +* `Review`: a space-separated list of parenthesized links to different forums threads about this proposal. Link text can be free-form but is encouraged to match the [standard grammar](#standard-review-links) whenever applicable. Required in all new proposal documents. -### Proposal templates - -When writing a formal proposal document, start with the most relevant template -given the primary subject of the proposal: - -- Use the [Swift template][swift-template] for proposals concerning the Swift - language, compiler, or standard library. -- Use the [Swift Package Manager template][swiftpm-template] for proposals - related to SwiftPM, including the design of its package manifest files and - command-line tools. -- Use the [Swift Testing template][swift-testing-template] for proposals focused - on Swift Testing features or public interfaces. - -### Proposal locations - -When opening a pull request to add a new proposal to the -[swift-evolution repository][swift-evolution-repo], place proposals which use -the [Swift][swift-template] or [Swift Package Manager][swiftpm-template] -templates in the top-level [proposals](/proposals) directory. Place proposals -which use the newer [Swift Testing template][swift-testing-template] in the -[proposals/testing](/proposals/testing) subdirectory. - -## Review process - -The review process for a particular proposal begins when a member of -the appropriate evolution workgroup accepts a pull request of a new or updated proposal into -the [swift-evolution repository][swift-evolution-repo]. That -member becomes the *review manager* for the proposal. The proposal -is assigned a proposal number (if it is a new proposal), and then enters -the review queue. If your proposal's accompanying implementation takes the form of a package, the review manager will merge your pull request into a new branch in the [swift-evolution-staging repository][swift-evolution-staging]. - -The review manager will work with the proposal authors to schedule the -review. Reviews usually last a single week, but can run longer for -particularly large or complex proposals. - -When the scheduled review period arrives, the review manager will post -the proposal to the ["Proposal reviews" section of the Swift forums][proposal-reviews] -with the proposal title and update the list of active -reviews. To avoid delays, it is important that the proposal authors be -available to answer questions, address feedback, and clarify their -intent during the review period. - -After the review has completed, the managing evolution workgroup will make a decision on -the proposal. The review manager is responsible for determining -consensus among the workgroup members, then reporting their decision -to the proposal authors and forums. The review manager will -update the proposal's state in the [swift-evolution -repository][swift-evolution-repo] to reflect that decision. +These standard fields should be provided in this order. Other fields can be added between `Status` and `Review`. + +The following header fields are used only in specific evolution areas: + +* `Upcoming Feature Flag`: an identifier in backticks. Used for language proposals where some or all of the content in the proposal is enabled only when a particular upcoming feature is enabled. ## Proposal states @@ -234,33 +247,51 @@ A given proposal can be in one of several states: contingent upon the inclusion of one or more revisions. * **Previewing**: The proposal has been accepted and is available for preview in the [Standard Library Preview package][preview-package]. -* **Implemented (Swift Next)**: +* **Implemented (Swift X.Y)**: The proposal has been implemented (for the specified version of Swift). If the proposal's implementation spans multiple version numbers, write the version number for which the implementation will be complete. -[swift-evolution-repo]: https://github.com/swiftlang/swift-evolution "Swift evolution repository" -[swift-evolution-staging]: https://github.com/swiftlang/swift-evolution-staging "Swift evolution staging repository" -[proposal-reviews]: https://forums.swift.org/c/evolution/proposal-reviews "'Proposal reviews' subcategory of the Swift forums" -[status-page]: https://www.swift.org/swift-evolution -[preview-package]: https://github.com/apple/swift-standard-library-preview/ -[language-steering-group]: https://www.swift.org/language-steering-group -[platform-steering-group]: https://www.swift.org/platform-steering-group -[testing-workgroup]: https://www.swift.org/testing-workgroup "Testing Workgroup page on Swift.org" -[swift-template]: proposal-templates/0000-swift-template.md "Swift proposal template" -[swiftpm-template]: proposal-templates/0000-swiftpm-template.md "Swift Package Manager proposal template" -[swift-testing-template]: proposal-templates/0000-swift-testing-template.md "Swift Testing proposal template" +## Standard review links + +While links in the `Review:` header field can have any text, they are encouraged to use standardized text matching the following grammar whenever that describes the target of the link with sufficient clarity: + +```text +review-label: + ordinal? standard-review-label + +# An ordinal should be provided if and only if there are multiple +# links of the same kind in the review field. +ordinal: + 'first' + 'second' + 'third' + 'fourth' + ... + +standard-review-label: + 'pitch' + 'review' + 'revision' + 'acceptance' ('with' 'modifications')? + 'rejection' + 'returned for revision' +``` + +This grammar assumes a single space between adjacent tokens. + +The unified review thread of a proposal that uses lightweight evolution review should be linked as `review`. ## Review announcement -When a proposal enters review, a new topic will be posted to the -["Proposal Reviews" subcategory of the Swift forums][proposal-reviews] using the -relevant announcement template below: +When a proposal enters full evolution review, a new topic will be posted to the appropriate section of the Swift forums using the appropriate announcement template below. + +There's no specific announcement template for a proposal using lightweight evolution review, but evolution workgroups should make it clear in the thread that the proposal is now under formal consideration. --- -
-Swift language, compiler, and standard library +
+Language and standard library Hello Swift community, @@ -304,7 +335,7 @@ Review Manager
-Swift Testing public interfaces and features +Testing Hello Swift community, @@ -370,3 +401,23 @@ Thank you, Review Manager
+ +
+ +[forums]: https://forums.swift.org/ +[forums-pitches]: https://forums.swift.org/c/evolution/pitches/5 +[forums-reviews]: https://forums.swift.org/c/evolution/proposal-reviews/21 +[spm]: https://www.swift.org/package-manager/ +[swift-evolution-repo]: https://github.com/swiftlang/swift-evolution "Swift evolution repository" +[swift-evolution-staging]: https://github.com/swiftlang/swift-evolution-staging "Swift evolution staging repository" +[proposal-reviews]: https://forums.swift.org/c/evolution/proposal-reviews "'Proposal reviews' subcategory of the Swift forums" +[status-page]: https://www.swift.org/swift-evolution +[preview-package]: https://github.com/apple/swift-standard-library-preview/ +[language-steering-group]: https://www.swift.org/language-steering-group +[platform-steering-group]: https://www.swift.org/platform-steering-group +[ecosystem-steering-group]: https://www.swift.org/ecosystem-steering-group +[testing-workgroup]: https://www.swift.org/testing-workgroup "Testing Workgroup page on Swift.org" +[swift-template]: proposal-templates/0000-swift-template.md "Swift proposal template" +[swiftpm-template]: proposal-templates/0000-swiftpm-template.md "Swift Package Manager proposal template" +[swift-testing-template]: proposal-templates/0000-swift-testing-template.md "Swift Testing proposal template" +[draft-pr]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests