Hello, Swift community.
"Manifestos" have historically served an important role in Swift's design. A manifesto pairs a long-form analysis of the current state of one area of the project with a high-level vision for how that area should evolve in the future. It establishes common terminology, propagates key conceptual models, and sets community expectations about the direction of the project. The impact of a good manifesto can be felt in every conversation that touches on that area in the future.
Unfortunately, manifestos also have a critical flaw, which is that it's never been clear what they really mean in the evolution process. Manifestos are not evolution proposals: they do not undergo evolution review, and they do not get formally accepted or rejected. Historically, they've often been written by active members of the Core Team, and often they've been reviewed and revised by the Core Team before being published, but this is neither guaranteed nor visible to the community. As a result, it can be hard for the community to know whether they should treat any given manifesto as speaking for more than just its author. Moreover, manifestos usually lay out a set of proposals that the author is arguing should be incorporated into Swift. If members of the Core Team seem to support a manifesto, what does that mean for those proposals when they come up for review? Are those reviews merely empty formalities?
These problems are worth fixing. The Swift project is changing how we handle these design documents by introducing a lightweight process for creating and approving them and setting clear expectations about what that approval means. To clearly distinguish documents created under the new process, we are also changing both where they are stored and what they are called. These documents are now called vision documents, and when they have been officially accepted, they will be stored in the evolution repository in the visions
directory.
Vision documents usually start by being solicited by the evolution workgroup with authority for that area. For areas within the Swift language and standard library, that is the Language Workgroup. While a vision is being developed, it is called a prospective vision, and it should be clearly identified as such. In this state, the vision carries no implicit endorsement.
Eventually, the appropriate evolution workgroup may decide to officially approve a vision. This is an endorsement of the entire document, but the strength of that endorsement varies from section to section:
-
It is a strong endorsement of the vision's description of the current state of this part of the project. The evolution workgroup agrees with what the vision has to say about the problems the project has in this area.
-
It is a strong endorsement of the vision's stated goals for this part of the language. The evolution workgroup agrees that these are the right goals for evolution in this area to strive for, and it agrees that the vision prioritizes different goals appropriately.
-
It is a somewhat weaker endorsement of the overall approach laid out by the vision. The evolution workgroup agrees that this seems like the right basic approach to take; if it can successfully carried out, it should achieve the goals the vision lays out. However, the evolution workgroup is not committed to the details of the approach, and it may change substantially as the vision is distilled into concrete proposals and reviewed.
-
It is only a very weak endorsement of the concrete ideas for proposals in the vision document. The evolution workgroup thinks these sound like the right ideas in the abstract but is not committed to any of them. The proposals will all need to go through normal evolution review, and they may be rejected or substantially changed from how they appear in the vision.
Once the vision is approved, it acts as a foundation for subsequent pitches and proposals in its area. Pitches and proposals that implement or build on part of a vision should generally link back to the vision document.
Vision documents are artifacts of the design process; they are not substitutes for language or release documentation. It is not expected that authors will continually update the vision document as the proposals emerging from it change. Revision may be appropriate if the vision document is actively causing confusion, for example because of a major shift in terminology since the document's development.
We hope that this new process for vision documents will clarify their role in evolution, and we invite comments and suggestions for how they could be improved.
John McCall
Language Workgroup Chair