|
| 1 | +# Swift Testing Feature name |
| 2 | + |
| 3 | +* Proposal: [ST-NNNN](NNNN-filename.md) |
| 4 | +* Authors: [Author 1](https://github.com/author1), [Author 2](https://github.com/author2) |
| 5 | +* Status: **Awaiting implementation** or **Awaiting review** |
| 6 | +* Bug: _if applicable_ [swiftlang/swift-testing#NNNNN](https://github.com/swiftlang/swift-testing/issues/NNNNN) |
| 7 | +* Implementation: [swiftlang/swift-testing#NNNNN](https://github.com/swiftlang/swift-testing/pull/NNNNN) |
| 8 | +* Previous Proposal: _if applicable_ [ST-XXXX](XXXX-filename.md) |
| 9 | +* Previous Revision: _if applicable_ [1](https://github.com/swiftlang/swift-evolution/blob/...commit-ID.../proposals/testing/NNNN-filename.md) |
| 10 | +* Review: ([pitch](https://forums.swift.org/...)) |
| 11 | + |
| 12 | +When filling out this template, you should delete or replace all of the text |
| 13 | +except for the section headers and the header fields above. For example, you |
| 14 | +should delete everything from this paragraph down to the Introduction section |
| 15 | +below. |
| 16 | + |
| 17 | +As a proposal author, you should fill out all of the header fields. Delete any |
| 18 | +header fields marked _if applicable_ that are not applicable to your proposal. |
| 19 | + |
| 20 | +When sharing a link to the proposal while it is still a PR, be sure to share a |
| 21 | +live link to the proposal, not an exact commit, so that readers will always see |
| 22 | +the latest version when you make changes. On GitHub, you can find this link by |
| 23 | +browsing the PR branch: from the PR page, click the "username wants to merge ... |
| 24 | +from username:my-branch-name" link and find the proposal file in that branch. |
| 25 | + |
| 26 | +`Status` should reflect the current implementation status while the proposal is |
| 27 | +still a PR. The proposal cannot be reviewed until an implementation is available, |
| 28 | +but early readers should see the correct status. |
| 29 | + |
| 30 | +`Bug` should be used when this proposal is fixing a bug with significant |
| 31 | +discussion in the bug report. It is not necessary to link bugs that do not |
| 32 | +contain significant discussion or that merely duplicate discussion linked |
| 33 | +somewhere else. Do not link bugs from private bug trackers. |
| 34 | + |
| 35 | +`Implementation` should link to the PR(s) implementing the feature. If the |
| 36 | +proposal has not been implemented yet, or if it simply codifies existing |
| 37 | +behavior, just say that. If the implementation has already been committed to the |
| 38 | +main branch (as an experimental feature or SPI), mention that. If the |
| 39 | +implementation is spread across multiple PRs, just link to the most important |
| 40 | +ones. |
| 41 | + |
| 42 | +`Previous Proposal` should be used when there is a specific line of succession |
| 43 | +between this proposal and another proposal. For example, this proposal might |
| 44 | +have been removed from a previous proposal so that it can be reviewed separately, |
| 45 | +or this proposal might supersede a previous proposal in some way that was felt |
| 46 | +to exceed the scope of a "revision". Include text briefly explaining the |
| 47 | +relationship, such as "Supersedes ST-1234" or "Extracted from ST-01234". If |
| 48 | +possible, link to a post explaining the relationship, such as a review decision |
| 49 | +that asked for part of the proposal to be split off. Otherwise, you can just |
| 50 | +link to the previous proposal. |
| 51 | + |
| 52 | +`Previous Revision` should be added after a major substantive revision of a |
| 53 | +proposal that has undergone review. It links to the previously reviewed revision. |
| 54 | +It is not necessary to add or update this field after minor editorial changes. |
| 55 | + |
| 56 | +`Review` is a history of all discussion threads about this proposal, in |
| 57 | +chronological order. Use these standardized link names: `pitch` `review` |
| 58 | +`revision` `acceptance` `rejection`. If there are multiple such threads, spell |
| 59 | +the ordinal out: `first pitch` `second review` etc. |
| 60 | + |
| 61 | +## Introduction |
| 62 | + |
| 63 | +A short description of what the feature is. Try to keep it to a single-paragraph |
| 64 | +"elevator pitch" so the reader understands what problem this proposal is |
| 65 | +addressing. |
| 66 | + |
| 67 | +## Motivation |
| 68 | + |
| 69 | +Describe the problems that this proposal seeks to address. If the problem is |
| 70 | +that some common pattern is currently hard to express, show how one can |
| 71 | +currently get a similar effect and describe its drawbacks. If it's completely |
| 72 | +new functionality that cannot be emulated, motivate why this new functionality |
| 73 | +would help Swift developers test their code more effectively. |
| 74 | + |
| 75 | +## Proposed solution |
| 76 | + |
| 77 | +Describe your solution to the problem. Provide examples and describe how they |
| 78 | +work. Show how your solution is better than current workarounds: is it cleaner, |
| 79 | +safer, or more efficient? |
| 80 | + |
| 81 | +This section doesn't have to be comprehensive. Focus on the most important parts |
| 82 | +of the proposal and make arguments about why the proposal is better than the |
| 83 | +status quo. |
| 84 | + |
| 85 | +## Detailed design |
| 86 | + |
| 87 | +Describe the design of the solution in detail. If it includes new API, show the |
| 88 | +full API and its documentation comments detailing what it does. If it involves |
| 89 | +new macro logic, describe the behavior changes and include a succinct example of |
| 90 | +the additions or modifications to the macro expansion code. The detail in this |
| 91 | +section should be sufficient for someone who is *not* one of the authors to be |
| 92 | +able to reasonably implement the feature. |
| 93 | + |
| 94 | +## Source compatibility |
| 95 | + |
| 96 | +Describe the impact of this proposal on source compatibility. As a general rule, |
| 97 | +all else being equal, test code that worked in previous releases of the testing |
| 98 | +library should work in new releases. That means both that it should continue to |
| 99 | +build and that it should continue to behave dynamically the same as it did |
| 100 | +before. |
| 101 | + |
| 102 | +This is not an absolute guarantee, and the testing library administrators will |
| 103 | +consider intentional compatibility breaks if their negative impact can be shown |
| 104 | +to be small and the current behavior is causing substantial problems in practice. |
| 105 | + |
| 106 | +For proposals that affect testing library API, consider the impact on existing |
| 107 | +clients. If clients provide a similar API, will type-checking find the right one? |
| 108 | +If the feature overloads an existing API, is it problematic that existing users |
| 109 | +of that API might start resolving to the new API? |
| 110 | + |
| 111 | +## Integration with supporting tools |
| 112 | + |
| 113 | +In this section, describe how this proposal affects tools which integrate with |
| 114 | +the testing library. Some features depend on supporting tools gaining awareness |
| 115 | +of the new feature for users to realize new benefits. Other features do not |
| 116 | +strictly require integration but bring improvement opportunities which are worth |
| 117 | +considering. Use this section to discuss any impact on tools. |
| 118 | + |
| 119 | +This section does need not to include details of how this proposal may be |
| 120 | +integrated with _specific_ tools, but it should consider the general ways that |
| 121 | +tools might support this feature and note any accompanying SPI intended for |
| 122 | +tools which are included in the implementation. Note that tools may evolve |
| 123 | +independently and have differing release schedules than the testing library, so |
| 124 | +special care should be taken to ensure compatibility across versions according |
| 125 | +to the needs of each tool. |
| 126 | + |
| 127 | +## Future directions |
| 128 | + |
| 129 | +Describe any interesting proposals that could build on this proposal in the |
| 130 | +future. This is especially important when these future directions inform the |
| 131 | +design of the proposal, for example by making sure an interface meant for tools |
| 132 | +integration can be extended to include additional information. |
| 133 | + |
| 134 | +The rest of the proposal should generally not talk about future directions |
| 135 | +except by referring to this section. It is important not to confuse reviewers |
| 136 | +about what is covered by this specific proposal. If there's a larger vision that |
| 137 | +needs to be explained in order to understand this proposal, consider starting a |
| 138 | +discussion thread on the forums to capture your broader thoughts. |
| 139 | + |
| 140 | +Avoid making affirmative statements in this section, such as "we will" or even |
| 141 | +"we should". Describe the proposals neutrally as possibilities to be considered |
| 142 | +in the future. |
| 143 | + |
| 144 | +Consider whether any of these future directions should really just be part of |
| 145 | +the current proposal. It's important to make focused, self-contained proposals |
| 146 | +that can be incrementally implemented and reviewed, but it's also good when |
| 147 | +proposals feel "complete" rather than leaving significant gaps in their design. |
| 148 | +An an example from the Swift project, when |
| 149 | +[SE-0193](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0193-cross-module-inlining-and-specialization.md) |
| 150 | +introduced the `@inlinable` attribute, it also included the `@usableFromInline` |
| 151 | +attribute so that declarations used in inlinable functions didn't have to be |
| 152 | +`public`. This was a relatively small addition to the proposal which avoided |
| 153 | +creating a serious usability problem for many adopters of `@inlinable`. |
| 154 | + |
| 155 | +## Alternatives considered |
| 156 | + |
| 157 | +Describe alternative approaches to addressing the same problem. This is an |
| 158 | +important part of most proposal documents. Reviewers are often familiar with |
| 159 | +other approaches prior to review and may have reasons to prefer them. This |
| 160 | +section is your first opportunity to try to convince them that your approach is |
| 161 | +the right one, and even if you don't fully succeed, you can help set the terms |
| 162 | +of the conversation and make the review a much more productive exchange of ideas. |
| 163 | + |
| 164 | +You should be fair about other proposals, but you do not have to be neutral; |
| 165 | +after all, you are specifically proposing something else. Describe any |
| 166 | +advantages these alternatives might have, but also be sure to explain the |
| 167 | +disadvantages that led you to prefer the approach in this proposal. |
| 168 | + |
| 169 | +You should update this section during the pitch phase to discuss any |
| 170 | +particularly interesting alternatives raised by the community. You do not need |
| 171 | +to list every idea raised during the pitch, just the ones you think raise points |
| 172 | +that are worth discussing. Of course, if you decide the alternative is more |
| 173 | +compelling than what's in the current proposal, you should change the main |
| 174 | +proposal; be sure to then discuss your previous proposal in this section and |
| 175 | +explain why the new idea is better. |
| 176 | + |
| 177 | +## Acknowledgments |
| 178 | + |
| 179 | +If significant changes or improvements suggested by members of the community |
| 180 | +were incorporated into the proposal as it developed, take a moment here to thank |
| 181 | +them for their contributions. This is a collaborative process, and everyone's |
| 182 | +input should receive recognition! |
| 183 | + |
| 184 | +Generally, you should not acknowledge anyone who is listed as a co-author. |
0 commit comments