Mandatory Toolchain and Sample Projects header fields and Experimenting section will allow developers to more easily experiment and be part of the discussion during the proposal review period.
Motivation
Experiment with a feature under review it's a important way to evaluate a proposal and even a well written and detailed proposal can benefit from having developers experiment with it. The proposal template could be improved to make it easier for anyone to try out the proposed functionality during the review period.
Proposed Solution
Add the following header fields to the proposal template: Toolchain and Sample Project alongside a new Experiment It section.
Toolchain
This field should point to a link where one can download a swift toolchain where the feature is implemented under a experimental flag.
Currently most proposals only mention that a feature is available in the main branch and although most of the time the feature lands in development snapshot available on Swift.org - Download Swift it's not that trivial for a newcomer to know this and sometimes a proposal review period even starts without a working snapshot.
The link should be available from day one and updated whenever possible during the review period.
One possibility would be to add an additional section on the website download page with toolchains dedicated to the proposals under review, this could allow a toolchain to be available even if for some reason it couldn't in the main snapshot.
Sample Project
This should point to a public repository for a swift package, ideally with a executable target, where there's a working code that highlights what the proposal author wants to be evaluated.
Experimenting
This section would contain a a standard text that instructs how to use the toolchain to experiment the sample project and any extra content that the author may optionally provide.
Sorry @mtsrodrigues but if I may ask, does this pitch come with a way for knowing all the features flags and which snapshots they are available on?
Like a comprehensive list of proposals, their SE numbers and the associated feature flag
This list is already available at Swift.org - Swift Evolution. The new toolchain, experimental feature flag and sample project header fields that I'm proposing could be added to this page.
The LSG talked about this today. It's always been a goal for reviewers to be able to experiment proposals, and we agree that the review process often makes that unnecessarily difficult; that's something we'd like to improve. However, we're concerned that requiring a sample project would substantially increase the burden on proposal authors. Examples embedded in proposal documents are often incomplete and "didactic", i.e. designed to demonstrate how the proposal works in the language rather than to present a compelling real-world use case. Writing a sample project that meaningfully exercises a feature and shows how it would be used in real code can be a lot of work. If authors want to take that on, that's great, and we'd like to feature that prominently in the review; but we're unwilling to take the step of requiring it. We're also concerned about the suggestion of permanence that would come from putting these things in the proposal document; this is a convenience offered to the evolution community for the duration of the review, not something that should become a permanent maintenance burden for the author.
What we're going to try is adding a "Try it out" section to the standard review post. That will link to a toolchain that people can use for the duration of the review, and if the proposal author wants to offer a sample project (as a standalone SPM project hosted in their own github repository), that can go in there, too. We think putting that in the review thread rather than the proposal document carries the right implications about how long it's expected to continue to work.
Yes, this is an accurate description of the approach that we are taking. See, for example, this recent review thread. What can we further clarify on this issue?
