python-pep-author

Files (11)

• SKILL.md
• pep-template.rst · assets/templates/
• gotchas.md
• metadata.json
• header-fields.md · references/
• pep-types.md · references/
• sections.md · references/
• status-lifecycle.md · references/
• workflow.md · references/
• check-pep.sh · scripts/
• new-pep.sh · scripts/

SKILL.md (first lines)

# Write a Python Enhancement Proposal (PEP)

A PEP is the design document the Python community uses to propose a new language
feature, a stdlib change, an interoperability standard, or a process/informational
guideline. This skill takes an author from a rough idea to a correctly-formatted,
process-compliant draft ready for submission to the [python/peps](https://github.com/python/peps)
repository.

The hard parts of a PEP are not the prose — they are getting the **type** right,
the **header preamble** valid, the **sections** complete to the acceptance bar,
and following the **process** (vetting, sponsorship, review). This skill bundles
two scripts for the deterministic parts and reference docs for the judgement calls.

## When to Apply

- The user asks to **write / draft / structure a PEP** or a "Python Enhancement Proposal".
- The user wants to **propose a Python language or standard-library feature** and needs it written up formally.
- The user has an idea they've been discussing on the Python Discourse and wants to **turn it into a PEP draft**.
- The user needs the **PEP template, header fields, or section structure** explained or generated.
- The user is **revising an existing PEP** (changing status, adding a Resolution, addressing review feedback).

Do **not** use this skill for internal company RFCs / design docs (use `dev-rfc`) — a
PEP is specifically a proposal to the upstream CPython / Python community governed by
[PEP 1](https://peps.python.org/pep-0001/).

## Prerequisites

- **Bash + coreutils** (`awk`, `sed`, `grep`, `date`) for the two scripts — present by default on macOS/Linux.
- A clone of, or a fork of, [github.com/python/peps](https://github.com/python/peps) only when you're ready to *submit* (Step 6). Drafting needs no repo.
- No Python runtime is required to draft or lint; the reference implementation (if any) is the author's separate codebase.

## Workflow Overview

```
1. Vet the idea ────► 2. Choose the type ────► 3. Scaffold the file
   (is it PEP-able?)     (Standards/Info/Process)   (scripts/new-pep.sh)
                                                          │
   6. Submit ◄──── 5. Self-check ◄──── 4. Draft each section
   (sponsor, PR)      (scripts/check-pep.sh)   (to the acceptance bar)
        │
        ▼
   7. Review & resolution ──► update Status + Resolution header
```

### 1. Vet the idea (before writing anything)

A PEP that duplicates prior work or isn't community-wide in scope will be rejected on
sight. Post the idea to the **Ideas** category of the [Python Discourse](https://discuss.python.org/c/ideas/6)
first (or the Typing / Packaging category if specialised). Confirm it's original,
applicable to the whole community, and not already settled by a past discussion.
See [references/workflow.md](references/workflow.md) for venues and what to check.

### 2. Choose the PEP type

There are exactly three: **Standards Track**, **Informational**, **Process**. The type
determines required headers (e.g. `Python-Version`, `Resolution`) and the bar for
acceptance. Pick with [references/pep-types.md](references/pep-types.md).

### 3. Scaffold the file

Generate a valid, correctly-headed reStructuredText file rather than hand-typing the
preamble (the field set and ordering are exact):

```bash
scripts/new-pep.sh \
  --title "A short descriptive title" \
  --author "Random J. User <random@example.com>" \
  --type "Standards Track" \
  --python-version 3.15            # Standards Track only; omit otherwise
```

This writes `pep-9999.rst` (`9999` = placeholder; PEP editors assign the real number),
sets `Status: Draft` and today's `Created` date, and enforces the 44-character title
limit. Run `scripts/new-pep.sh` with no args for full usage.

### 4. Draft each section

Fill the body sections in the canonical PEP 12 order: **Abstract → Motivation →
Specification → Rationale → Backwards Compatibility → Security Implications → How to
Teach This → Reference Implementation → Rejected Ideas → Open Issues →
Acknowledgements → Footnotes → Change History → Copyright**.
Each section has a specific job and a quality bar — read
[references/sections.md](references/sections.md) before drafting, and consult
[references/header-fields.md](references/header-fields.md) for any header you need to
fill in (Sponsor, Discussions-To, Requires, etc.).

The acceptance bar (from PEP 1): the proposal must be a **clear and complete**
description, represent a **net improvement**, have a **solid** implementation that
doesn't unduly complicate the interpreter, and be **"pythonic"**. Write to that bar.

### 5. Self-check the draft

Lint the headers and required structure before showing it to anyone:

```bash
scripts/check-pep.sh pep-9999.rst
```

It verifies the required headers are present, the title length, valid `Status`/`Type`
values, the `Created` date format, the mandatory CC0 copyright notice, and an
`Abstract` section — reporting PASS / WARN / FAIL and exiting non-zero on any FAIL.
Fix every FAIL.

### 6. Submit

If **no co-author is a CPython core developer**, you must first find a **sponsor**
(a core developer who shepherds the PEP). Then fork python/peps, add `pep-NNNN.rst`,
list authors/sponsors in `.github/CODEOWNERS`, and open a pull request. PEP editors
review for format and soundness and assign the number. Full steps and the role
definitions are in [references/workflow.md](references/workflow.md).

### 7. Review & resolution

When the authors (and sponsor) judge it ready, content review and the
accept/reject decision rest with the **Steering Council** (or an appointed
**PEP-Delegate**). On a decision, update the `Status` and add a `Resolution`
header linking to the pronouncement. The full status lifecycle and valid
transitions are in [references/status-lifecycle.md](references/status-lifecycle.md).

## Reference Files

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills