Skip to content

Update proposal template and documented states to standardize current usage. #497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 17, 2016
Merged

Update proposal template and documented states to standardize current usage. #497

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ceac393
Add additional fields to the proposal template.
bjlanier Aug 12, 2016
18333c3
Update possible proposal states to reflect and standardize current us…
bjlanier Aug 12, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions 0000-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,22 @@
# Feature name

* Proposal: [SE-NNNN](NNNN-filename.md)
* Author: [Swift Developer](https://github.com/swiftdev)
* Authors: [Author 1](https://github.com/swiftdev), [Author 2](https://github.com/swiftdev)
Copy link
Contributor

@benrimmington benrimmington Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single author is more common, so maybe that part of the template shouldn't change (to avoid d709546).

Copy link
Member

@amartini51 amartini51 Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The old template used "Author(s)" which matches singular and plural, which lead to the problem you noted because the "(s)" was always left in place.

The new template uses the plural form in places where a list is allowed. This lets it show you how to format that list (separate entries by commas, not just spaces, omitting the word "and"), and you delete things you don't need. So, if there's only one author, you would write Author: [Some Name](https://github.com/swiftdev) in your actual proposal.

I think the clarity is worth the small burden of asking proposal authors to delete a bit of extra text if they don't need it.

Copy link
Contributor

@benrimmington benrimmington Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem can already be seen in #499 (e.g. "Authors" and "Bugs" in SE-0011).

Copy link
Contributor Author

@bjlanier bjlanier Aug 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, good spot!

* Review Manager: TBD
* Status: **Awaiting review**
* Review manager: TBD

*During the review process, add the following fields as needed:*

* Decision Notes: [Rationale](https://lists.swift.org/pipermail/swift-evolution/), [Additional Commentary](https://lists.swift.org/pipermail/swift-evolution/)
Copy link
Contributor

@benrimmington benrimmington Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the discussion and review threads be moved into the header?

* Feedback:
  [Pitch]    (https://lists.swift.org/pipermail/swift-evolution/),
  [Review]   (https://lists.swift.org/pipermail/swift-evolution/),
  [Rationale](https://lists.swift.org/pipermail/swift-evolution/)

Copy link
Contributor Author

@bjlanier bjlanier Aug 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's an interesting suggestion. We decided to use Decision Notes and keep the header information related to the outcome of a review, since this information is usually added by the review manager.

* Bugs: [SR-NNNN](https://bugs.swift.org/browse/SR-NNNN), [SR-MMMM](https://bugs.swift.org/browse/SR-MMMM)
Copy link
Contributor

@benrimmington benrimmington Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A single bug report is expected. The only current exceptions are SE-0007 and SE-0061.

Copy link
Contributor Author

@bjlanier bjlanier Aug 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's true, at least at the moment. The plural form is meant to serve as an example of the format to use when there's more than one bug.

* Previous Revision: [1](https://github.com/apple/swift-evolution/blob/...commit-ID.../proposals/NNNN-filename.md)
* Previous Proposal: [SE-XXXX](XXXX-filename.md)

## Introduction

A short description of what the feature is. Try to keep it to a
single-paragraph "elevator pitch" so the reader understands what
problem this proposal is addressing.
problem this proposal is addressing.

Swift-evolution thread: [Discussion thread topic for that proposal](https://lists.swift.org/pipermail/swift-evolution/)

Expand Down
32 changes: 21 additions & 11 deletions process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,23 +82,33 @@ repository][swift-evolution-repo] to reflect that decision.
## Proposal states
A given proposal can be in one of several states:

* **Awaiting review**: the proposal is awaiting review. Once known,
* **Awaiting review**: The proposal is awaiting review. Once known,
the dates for the actual review will be placed in the proposal
document and updated in the [list of proposals](proposals.xml). When the
review period begins, the review manager will update the state to
*under review*.
* **Under review**: the proposal is undergoing public review on the [swift-evolution mailing list][swift-evolution-mailing-list].
* **Under revision**: the proposal is undergoing revision by the
author(s) based on feedback from the review.
* **Deferred**: consideration of the proposal has been deferred
*Active review*.
* **Scheduled for review (MONTH DAY...MONTH DAY)**: The public review of the proposal
on the [swift-evolution mailing list][swift-evolution-mailing-list]
has been scheduled for the specified date range.
* **Active review (MONTH DAY...MONTH DAY)**: The proposal is undergoing public review
on the [swift-evolution mailing list][swift-evolution-mailing-list].
The review will continue through the specified date range.
* **Returned for revision**: The proposal has been returned from review
for additional revision to the current draft.
* **Withdrawn**: The proposal has been withdrawn by the original submitter.
* **Deferred**: Consideration of the proposal has been deferred
because it does not meet the [goals of the upcoming major Swift
release](README.md). Deferred proposals will be reconsidered when
scoping the next major Swift release.
* **Accepted**: the proposal has been accepted and is either awaiting
implementation or is actively being implemented. Once a proposal
enters the "accepted" state, it gets placed into its [target Swift
release](README.md).
* **Rejected**: the proposal has been considered and rejected.
* **Accepted**: The proposal has been accepted and is either awaiting
implementation or is actively being implemented.
* **Accepted with revisions**: The proposal has been accepted,
contingent upon the inclusion of one or more revisions.
* **Rejected**: The proposal has been considered and rejected.
* **Implemented (Swift VERSION)**: The proposal has been implemented.
Append the version number in parentheses—for example: Implemented (Swift 2.2).
Copy link
Contributor

@benrimmington benrimmington Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the version number always include the minor component?

* **Implemented (Swift MAJOR.MINOR)**: The proposal has been implemented.
  Append the version number in parentheses—for example: Implemented (Swift 3.0).

This is consistent with the output of the swift -version command.
It would distinguish between Swift 3.0 and Swift 3.1 when searching.

Copy link
Member

@amartini51 amartini51 Aug 16, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "dot zero" version of Swift are normally styled with only the major version number. (For example, on the Swift blog and in Xcode release notes.)

You can include the paren in your search to limit — for example git grep "Implemented (Swift 3)" gives you Swift 3.0 only versus git grep "Implemented (Swift 3" gives you all Swift versions that start with a three.

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/apple/swift-evolution "Swift evolution repository"
[swift-evolution-mailing-list]: https://swift.org/community/#swift-evolution "Swift evolution mailing list"
Expand Down