Hi All,
I’m a big fan of how Swift (the programming language) handles feature proposals. You can learn more about it in their process readme on the swift-evolution repo.
A really cool part of it is they also utilize GitHub-pages to visualize the proposals with some html/css/js in the GitHub repo. Theoretically we could use their webpage rendering code (with some modifications) to visualize our proposals.
The proposals are submitted in markdown via a pull request and merged into the master repo, which admittedly might be a bit difficult for those who don’t use GitHub.
The Swift Evolution proposal template looks like this:
Feature name
During the review process, add the following fields as needed:
- Implementation: apple/swift#NNNNN
- Decision Notes: Rationale, Additional Commentary
- Bugs: SR-NNNN, SR-MMMM
- Previous Revision: 1
- Previous Proposal: SE-XXXX
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.
Swift-evolution thread: Discussion thread topic for that proposal
Motivation
Describe the problems that this proposal seeks to address. If the
problem is that some common pattern is currently hard to express, show
how one can currently get a similar effect and describe its
drawbacks. If it’s completely new functionality that cannot be
emulated, motivate why this new functionality would help Swift
developers create better Swift code.
Proposed solution
Describe your solution to the problem. Provide examples and describe
how they work. Show how your solution is better than current
workarounds: is it cleaner, safer, or more efficient?
Detailed design
Describe the design of the solution in detail. If it involves new
syntax in the language, show the additions and changes to the Swift
grammar. If it’s a new API, show the full API and its documentation
comments detailing what it does. The detail in this section should be
sufficient for someone who is not one of the authors to be able to
reasonably implement the feature.
Source compatibility
Relative to the Swift 3 evolution process, the source compatibility
requirements for Swift 4 are much more stringent: we should only
break source compatibility if the Swift 3 constructs were actively
harmful in some way, the volume of affected Swift 3 code is relatively
small, and we can provide source compatibility (in Swift 3
compatibility mode) and migration.
Will existing correct Swift 3 or Swift 4 applications stop compiling
due to this change? Will applications still compile but produce
different behavior than they used to? If “yes” to either of these, is
it possible for the Swift 4 compiler to accept the old syntax in its
Swift 3 compatibility mode? Is it possible to automatically migrate
from the old syntax to the new syntax? Can Swift applications be
written in a common subset that works both with Swift 3 and Swift 4 to
aid in migration?
Effect on ABI stability
Does the proposal change the ABI of existing language features? The
ABI comprises all aspects of the code generation model and interaction
with the Swift runtime, including such things as calling conventions,
the layout of data types, and the behavior of dynamic features in the
language (reflection, dynamic dispatch, dynamic casting via as?
,
etc.). Purely syntactic changes rarely change existing ABI. Additive
features may extend the ABI but, unless they extend some fundamental
runtime behavior (such as the aforementioned dynamic features), they
won’t change the existing ABI.
Features that don’t change the existing ABI are considered out of
scope for Swift 4 stage 1. However, additive features
that would reshape the standard library in a way that changes its ABI,
such as where clauses for associated
types,
can be in scope. If this proposal could be used to improve the
standard library in ways that would affect its ABI, describe them
here.
Effect on API resilience
API resilience describes the changes one can make to a public API
without breaking its ABI. Does this proposal introduce features that
would become part of a public API? If so, what kinds of changes can be
made without breaking ABI? Can this feature be added/removed without
breaking ABI? For more information about the resilience model, see the
library evolution
document
in the Swift repository.
Alternatives considered
Describe alternative approaches to addressing the same problem, and
why you chose this approach instead.