Proposal Design and Implementation using a single Pull Request

Note: This document describes in detail a new process for writing design documentation for new features in mysql-server. It has been extensively reviewed within senior MySQL engineering and is authoritative immediately upon publication. (September 1, 2026) Note that this obsoletes most of the previous guidance for proposing new features, in particular: While you'd still create a github issue for project management and tracking purposes, the issue is no longer the place to write and review the entire design, nor do you attach a pdf or markdown file to it. Instead the majority of your proposal is now a markdown file in the mysql-server repo itself, under a new directory design/. Said file is still the good old worklog format that we've used since forever. It is just the tooling and process that is changing, not the content.

This file itself will also live inside the mysql-server repository, and its canonical URL will be https://github.com/mysql/mysql-server/tree/trunk/Docs/contributing/design-and-implementation-pull-request.md.

The mysql-community wiki is used as an interim location while we wait for this file to appear in the public mysql-server repo.

---

Contributing to MySQL | mysql-server CONTRIBUTING.md

---

Proposal Design and Implementation using a single Pull Request

As MySQL development moves to GitHub, design specifications should be reviewed through pull requests alongside the source code. This proposal introduces a top-level design/ directory in the MySQL repository, containing design specifications as Markdown files. This makes design review visible, traceable, and integrated with the normal development workflow. Approved specifications become part of the repository history and remain available to developers maintaining the implementation later.

Repository structure

The repository should contain a top-level design/ directory organized by module. The module structure should follow the existing WorkLog queue/module organization where practical.

design/
├── README.md                 # How the design-review process works
├── TEMPLATE.md               # Template for new design specifications
├── binary-log/
├── innodb/
├── optimizer/
├── parser/
├── replication/
├── runtime/
├── security/
└── server/

The README.md file should define the process, including review expectations, ownership, filename conventions, the relationship between design and implementation review, and conventions for linking Issues and pull requests.

Each design specification should be stored as a Markdown file in the relevant module directory. The filename should contain the number of the primary GitHub Issue followed by a short description:

design/<module>/<issue-number>-<short-description>.md

For example:

design/optimizer/12345-hash-join-spill-to-disk.md
design/innodb/23456-online-ddl-improvements.md

If the Markdown file refers to additional files, these files should be placed in a subdirectory with the same name (excluding the .md suffix:

# Small design
design/optimizer/12345-hash-join-spill-to-disk.md

# Optional supplementary artifacts for a small design
design/optimizer/12345-hash-join-spill-to-disk/
  diagram.svg
  benchmark-results.md

# Larger design
design/optimizer/12345-hash-join-spill-to-disk.md
design/optimizer/12345-hash-join-spill-to-disk/
  requirements.md
  high-level-design.md
  low-level-design.md
  diagram.svg

If a design covers several GitHub Issues, one should be identified as the primary tracking Issue and used in the filename. All related Issues should be listed in the specification.

Design-review workflow

1. One or more GitHub Issues are created for the feature or project.
2. The designer creates a branch containing the initial design specification under design/<module>/.
3. The designer opens a pull request and requests review from the relevant design reviewers.
4. The pull-request description links to the corresponding Issues and design specification:

## Tracking

- Primary issue: #12345
- Related issues: #12346, #12347
- Design: design/optimizer/12345-hash-join-spill-to-disk.md

5. The author adds a reference to the design-review pull request in each corresponding GitHub Issue:

Design review: #67890

6. Design discussion takes place directly in the pull request. Revisions to the design specification are made as commits on the branch.
7. Implementation may take place on the same branch and in the same pull request. It is not necessary to wait for design approval before starting implementation.
8. Before the pull request is merged, both the design and the implementation must be approved. Design and implementation may be reviewed and approved by different people.
9. Changes discovered during implementation should be reflected in the design specification before the implementation is merged. The merged specification should accurately describe the implementation delivered by the pull request or project.
10. The pull-request description should use an issue-closing keyword only for Issues that are fully resolved by the merge:

Fixes #12345

Issues that are related but not completed should be referenced without an issue-closing keyword.

GitHub closes linked Issues when a pull request using a supported closing keyword is merged into the default branch. See GitHub’s documentation on linking pull requests and Issues.

Separate design and implementation pull requests

For modest and well-bounded changes, the design specification and implementation may be developed and reviewed in the same pull request.

For large, risky, cross-module, or long-running projects, the approved design may instead be merged in a design-only pull request. Implementation can then proceed through one or more separate pull requests. (This is an exception and not the rule; most issues should merge the design and implementation together.)

A separate workflow may look like this:

GitHub Issues
      │
      ▼
Design pull request with Status: Draft
      │
      ▼
Approved design merged with Status: Accepted
      │
      ├──────────────┬──────────────┐
      ▼              ▼              ▼
Implementation PR  Implementation PR  Implementation PR
      └──────────────┴──────────────┘
                     │
                     ▼
       Final design updated Status: Implemented

In this workflow:

• The design-only pull request should use neutral references such as Related to #12345; it should not close the implementation Issues.
• The merged design specification should contain Status: Accepted immediately after its Issue references.
• Each implementation pull request should reference the relevant Issues and the merged design specification.
• Each corresponding Issue should reference both the design-review pull request and the relevant implementation pull requests.
• A project may cover several Issues and may be delivered through several implementation pull requests.
• Implementation-driven changes to the design should be committed to the design specification as part of the implementation pull requests.
• Status: Accepted should remain until the planned implementation has been completed. The final implementation pull request should change it to Status: Implemented.
• Only Issues completed by a particular implementation pull request should be closed by that pull request.

Design and implementation approval

Design approval and implementation approval are separate responsibilities, even when both are performed in the same pull request.

A pull request may contain code before the design is approved. However, it must not be merged until:

• The design has been approved by the relevant design reviewers.
• The implementation has been approved by the relevant code reviewers.
• Material differences between the approved design and implementation have been reflected in the specification.
• The updated specification has received any necessary renewed design approval.

The repository process should make it possible to determine which approval applies to the design and which applies to the implementation. This may be done through requested reviewer roles, labels, review comments, or another lightweight convention defined in design/README.md.

Ownership and reviewers

Each module directory under design/ should have designated owners. These owners should be configured through the repository’s CODEOWNERS file so that relevant reviewers are requested automatically.

The following rules should apply:

• A design requires approval from the owners of the affected module.
• A cross-module design requires reviewers from each materially affected module.
• Additional specialist reviewers should be requested when the design has significant implications for areas such as security, replication, upgrade behavior, persisted data, performance, or observability.
• The author of a design cannot provide its required design approval.
• Implementation approval follows the ownership rules for the affected source code and may be provided by different reviewers.

design/README.md should document how required reviewers are determined and how design approval is recorded.

Responsibilities of the Issue and design specification

The GitHub Issue and design specification have different purposes and should not duplicate each other unnecessarily.

The GitHub Issue is the authoritative record for:

• The problem and motivation.
• The intended outcome.
• Broad scope and acceptance criteria.
• Project status, priority, and other tracking information.

The design specification is the authoritative record for:

• Precise functional and non-functional requirements.
• The proposed architecture and behavior.
• Interfaces and implementation approach.
• Important alternatives and trade-offs.
• Compatibility, upgrade, security, performance, and operational implications.
• Testing and validation.

Requirements may be summarized in the Issue, but their detailed and normative form should reside in the design specification. Information that changes as the design evolves should have one authoritative location and be linked from the other location rather than copied. Each design specification should contain a short reference to its primary and related Issues immediately after the title.

Linking conventions

The relationship between Issues, design specifications, and pull requests should be bidirectional. A pull request should contain a tracking section such as:

## Tracking

- Primary issue: #12345
- Related issues: #12346, #12347
- Design: `design/optimizer/12345-hash-join-spill-to-disk.md`

Each related Issue should contain links to the applicable pull requests:

Design review: #67890
Implementation: #67910, #67911

When references cross repository boundaries, the fully qualified form should be used:

mysql/mysql-server#12345

Closing keywords such as Fixes, Closes, and Resolves should be reserved for implementation pull requests that complete the referenced Issue. Design-only pull requests and partial implementation pull requests should use neutral references.

Lifecycle of a design specification

A design specification records the design for a particular feature or project.

The specification should be updated during implementation so that it accurately describes what is delivered. This applies whether the implementation is in the same pull request or is divided across several pull requests.

Once the implementation has been completed and merged, the specification should be treated as a historical record and should not normally be updated to describe later changes.

A later task that changes the design should create its own Issue and, when appropriate, its own design specification. The new specification should reference the earlier design and explain which parts are being extended or changed. The earlier specification remains an accurate description of the work for which it was created.

A design merged before its implementation should contain:

Status: Accepted

The final implementation pull request should remove this line after the specification has been updated to reflect the completed implementation. No other lifecycle status is required.

Benefits

• Design discussions and decisions are recorded with the code.
• Reviewers can compare the implementation directly with the agreed design.
• Specifications are versioned, searchable, and retained with the source code.
• Future maintainers can find the rationale for significant changes without relying on a separate system.
• The process uses the same pull-request tools and review practices as implementation work.
• Issues, specifications, and pull requests have explicit bidirectional links.
• Design and implementation can be approved by the people best qualified to review each.
• A single design can support multiple Issues and implementation pull requests.
• The merged specification reflects the implementation delivered by the project.

Appendix: design/_TEMPLATE.md

Disclaimer: The below is just a quick attempt to capture the established Worklog format. The above proposal is intended to change where designs live and how they are reviewed, not to replace the existing design format.

# <Design title>

Primary GitHub Issue: #<issue number>
Related GitHub Issues: #<issue number>, #<issue number>
Design review PR: #<pull request number>

<!--
Add the following line only when the design is merged before implementation.
Remove it in the pull request that completes the planned implementation.

Status: Proposed
-->

## Description

Briefly summarize the proposed change.

The GitHub Issues are the authoritative source for the problem, motivation,
broad scope, acceptance criteria, and project tracking. Refer to them instead
of duplicating that information here.

## Functional Requirements

List the externally observable and other functional requirements.

Use stable identifiers so that the design, implementation, and tests can
refer to individual requirements.

FR1. ...

FR2. ...

If there are no functional requirements, state:

None.

## Non-Functional Requirements

List requirements concerning performance, resource use, compatibility,
security, reliability, maintainability, or other quality attributes.

Use stable identifiers.

NFR1. ...

NFR2. ...

If there are no non-functional requirements, state:

None.

## High Level Architecture

Describe the overall approach, major components, interactions, data flow,
and externally visible behavior.

Explain the important design choices and alternatives considered.

## Low Level Design

Describe the implementation in sufficient detail for reviewers to evaluate
it. Include the applicable topics from the following list:

- New or changed interfaces
- Data structures and algorithms
- Error and warning handling
- Persisted data and file-format changes
- Upgrade and downgrade behavior
- Replication behavior and compatibility
- Concurrency, locking, and recovery
- Security implications
- Performance and resource use
- Observability and diagnostics
- Affected source-code areas

For topics that would normally be relevant but are unaffected, state that
there is no impact.

## Alternatives Considered

Describe material alternatives and why they were not selected.

If no material alternatives were considered, state:

None.

## Testing

Describe how the functional and non-functional requirements will be
validated.

Identify required unit tests, MTR tests, integration tests, performance
tests, upgrade tests, or other validation as applicable.

Each validation item should identify the functional or non-functional 
requirement, and relevant design section, that it validates.

## References

- Primary GitHub Issue: #<issue number>
- Related GitHub Issues: #<issue number>, #<issue number>
- Design review PR: #<pull request number>
- Implementation PRs: #<pull request number>, #<pull request number>
- Related WorkLogs, designs, source code, or external documentation