Skip to content

Conversation

@rjmccall
Copy link
Contributor

@rjmccall rjmccall commented Sep 11, 2025

The focus of this change is on generally fixing and improving the documentation. For now, I am specifically trying to avoid resolving questions like whether SPM proposals should be part of the SE namespace and whether all evolution reviews should share a common category on the forums. The goal there is to document the current evolution process; if an evolution workgroup changes its practice in the future, editing this file will be the way it officially documents its new process.

An earlier version of this PR also laid out a lightweight evolution review process. I have removed this from the PR, not because I am uninterested in adding it, but because I want to land the general documentation improvements separately.

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).
    • 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
Copy link
Contributor

@stmontgomery stmontgomery left a comment

Choose a reason for hiding this comment

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

I think there's one small formatting issue outstanding (#2953 (comment)) but broadly speaking this is a great improvement to the process docs, thanks!

…ion.

- 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).
  - 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.
Co-authored-by: Xiaodi Wu <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

evolution process A change to the meta-content of evolution, e.g. the process documentation or templates

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants