Pitch: Improve the Proposal Template for better feature experimentation


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.


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.


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.


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.


I've drafted the new proposed template.

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

1 Like

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.

Okay & thanks

Hi @beccadax, @hborla, @Joe_Groff Do you have any comments on my suggestions?

Hi, Mateus. I'll put this on the agenda for the Language Steering Group to discuss. Today is a holiday in the U.S., though.


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.


That's sounds good and I think it's enough to solve the problems that I've raised. Thank you all for the quick response.

1 Like

Any update on this?

The issue is resolved as described above. What update are you looking for?

Was referring to this

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?


Sorry, I didn't notice that :pensive: