Skip to content

Commit 7207353

Browse files
stmontgomerystmontgomery
authored
Add a proposal template for Swift Testing (#2709)
* Add a proposal template for Swift Testing * Update URL template for "Previous revision" link * Switch to /proposals/testing subdirectory
1 parent e62f7da commit 7207353

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed

‎proposal-templates/0000-swift-testing-template.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Swift Testing Feature name
2+
3+
* Proposal: [SWT-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_ [SWT-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 SWT-1234" or "Extracted from SWT-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

Comments
 (0)