[Accepted with modifications] SE-0356: Swift Snippets

Hi folks,

The review of SE-0356: Swift Snippets has concluded. The review feedback focused the following topics:

  1. The ability to customize the location of the Snippets source code.
  2. The ability to use Snippets as the underpinning for step-by-step guides, which requires additional primitives to presents "slices" of snippets, enabling progressive disclosure.
  3. The best syntax for defining the above slices, and communicate show/hide semantics
  4. The differences and tradeoffs between snippets, literate programing, and code listings.

While alternative approaches such as literate programing have advantages, the core team feels Snippets solve a real need in the Swift ecosystem in a focused and pragmatic way, adding immediate value, while paving the path for future evolution and improvements. As such, the proposal has been accepted with the following modifications:

  1. Update the proposal to allow users to override the default top level directory for Snippets (in the Package manifest). There may be some restrictions around this such as the custom location cannot overlap with source directories.
  2. Update the proposal to include a design for Snippets slices (as currently described in the future directions section), as well as step-by-step guides based on such slices.
  3. Update the proposal to more robustly describe how Snippets are different from literate programming and embedded code listing, highlighting the tradeoffs and why Snippets is the preferred solution. These alternatives are already mentioned in the proposal but have been brought up again the review, as such, it would be good to bring additional details from the review thread back to the proposal for future readers.
  4. Add additional clarifications in the body of the proposal about which dependencies are supported and which are not ,and reference the future direction section where this is discussed.
  5. Add additional clarifications in the future direction section about improving the infrastructure of testing Snippets (beyond just building them).

The authors revised the proposal to include these changes, and the core team accepted the proposal with these modifications.

Thank you to the proposal authors and everyone who participated in the review.

Tom Doron,
Review Manager

14 Likes

Super excited about this and that the amendments 1. and 2. are considered to be included in this acceptance -- these really open up quite a world of use-cases for small library developers, thank you! :partying_face:

3 Likes