Skip to content

Restructure the evolution process documentation #2953

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Restructure the evolution process documentation #2953

wants to merge 4 commits into from

Conversation

rjmccall
Copy link
Contributor

@rjmccall rjmccall commented Sep 11, 2025 •
edited
Loading

Summary of changes:

  • Generalized some of the early wording to not just talk about the language and standard library
  • Moved the list of covered evolution areas from the Scope section to a later and more comprehensive Evolution Areas section
  • Unified the discussion about what is and is not covered by the evolution process into the early "scope" section
  • Changed some of the wording around when bug fixes are effectively design changes
  • Turned the Community Structure section into an Evolution Workgroups section:
    • Moved earlier in document.
    • Removed list of specific workgroups (now covered comprehensively by Evolution Areas).
    • Added brief discussion of Core Team delegation.
    • Added text giving workgroups authority for deciding how the process applies in their area.
    • Added text describing how cross-area proposals should be managed.
  • Added an Evolution review section:
    • Added a quick summary of the review process (proposal development + open review).
    • Break this down into full and lightweight evolution processes, with guidelines about what sorts of changes are appropriate for both.
    • Permit summary judgments, with caution.
  • Greatly expanded Participation section:
    • Added extensive guidance for participating in review.
    • Moved "How to Propose a Change" section into this section. Extensively reworded guidelines.
    • Moved discussion of focus areas to a separate section near end of document.
  • Added Evolution Areas section:
    • Describes three existing evolution areas, their workgroups, and the details of the evolution process used in each area
    • Fixed the description of package manager proposals, which the current document still assigns to the PSG instead of the ESG.
  • New Focus Areas section:
    • Removed from proposal guidance
    • Weakened wording to reflect actual practice
  • Changes to final sections of interest primarily to workgroups:
    • Moved the proposal status flowchart into this section
    • Added a section about generic proposal document structure: required fields, etc.

@rjmccall rjmccall added the evolution process A change to the meta-content of evolution, e.g. the process documentation or templates label Sep 11, 2025
@rjmccall
Restructure the evolution process documentation to better explain the
a4a2170 
new world of multiple evolution workgroups with slightly different
processes.
@rjmccall
Outline the evolution review process separately from the participation
7f452d9 
guidelines, and describe a new lightweight review process that combines
the pitch and review stages.
@rjmccall
Revise the description of the full and lightweight review processes
bd01013 
to be a little clearer. Make it clear that lightweight review should
only be used with approval from a steering group or the Core Team.

Update a few other sections in response to the introduction of
lightweight review.
FranzBusch
FranzBusch reviewed Sep 19, 2025
View reviewed changes
@rjmccall
Authority over SPM proposals actually resides with the ESG now.
011c702 
I copied this from the existing document, which apparently never got
updated.
xedin
xedin reviewed Sep 21, 2025
View reviewed changes
process.md
through constructive criticism and, eventually, determine the
direction of Swift. When writing your review, here are some questions
you might want to answer in your review:
Language and standard library proposals use full evolution review. They are pitched in the [Evolution > Pitches][forum-pitches] section of the Swift forums and reviewed in the [Evolution > Proposal Reviews][forums-reviews] section.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: here and few other places below need to be fixed to use “forums-pitches”.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@FranzBusch FranzBusch FranzBusch approved these changes

+2 more reviewers

@xedin xedin xedin left review comments

@ktoso ktoso ktoso approved these changes

Reviewers whose approvals may not affect merge requirements
Assignees
No one assigned
Labels
evolution process A change to the meta-content of evolution, e.g. the process documentation or templates
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@rjmccall @xedin @ktoso @FranzBusch