Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

JEP-0000: Jumpstarter Enhancement Proposal Process

Field

Value

JEP

0000

Title

Jumpstarter Enhancement Proposal Process

Author(s)

Jumpstarter Maintainers

Status

Active

Type

Process

Created

2026-04-06

Discussion

PR #423

Abstract

This document defines the Jumpstarter Enhancement Proposal (JEP) process — the mechanism by which substantial changes to the Jumpstarter project are proposed, discussed, and decided upon. JEPs provide a consistent, transparent record of design decisions for the Jumpstarter hardware-in-the-loop (HiL) testing framework and its ecosystem of drivers, CLI tools, operator components, and protocol definitions.

Motivation

As Jumpstarter grows in contributors, drivers, and production deployments, the project needs a structured way to propose and evaluate changes that go beyond routine bug fixes and minor improvements. An informal “open a PR and see what happens” approach doesn’t scale when changes touch hardware interfaces, gRPC protocol definitions, operator CRDs, or the driver plugin architecture — areas where mistakes are expensive to reverse.

The JEP process gives the community:

  • Visibility — a single place to discover what’s being proposed, what’s been decided, and why.

  • Structured discussion — a template that forces authors to think through motivation, hardware implications, backward compatibility, and testing before code is written.

  • Historical record — versioned markdown files in the repository whose git history captures the evolution of each proposal.

  • Inclusive governance — a lightweight, PR-based workflow that any contributor can participate in, regardless of commit access.

What Requires a JEP

Not every change needs a JEP. Use the following guidelines:

A JEP is required for:

  • New features or subsystems in the core framework (e.g., a new lease scheduling strategy, a new exporter transport mechanism).

  • Changes to the gRPC protocol (.proto files) or the operator CRD schema.

  • New driver interface contracts or modifications to existing driver base classes.

  • Changes to the jmp CLI that alter user-facing behavior in breaking ways.

  • Introduction of new infrastructure requirements (e.g., requiring a new Kubernetes operator dependency, adding a new container runtime assumption).

  • Significant changes to the packaging or distribution model (e.g., modifying the packages/ monorepo structure, changing the private package index behavior).

  • Process or governance changes (like this JEP itself).

A JEP is NOT required for:

  • Bug fixes and minor patches.

  • New drivers that follow the existing driver scaffold and don’t modify framework interfaces (use the standard driver contribution workflow instead).

  • Documentation improvements.

  • Dependency version bumps (unless they introduce breaking changes).

  • Refactoring that doesn’t change public APIs.

  • Test improvements.

When in doubt, ask in Matrix or open a GitHub issue to gauge whether your idea warrants a JEP.

JEP Types

Type

Description

Standards Track

Proposes a new feature or implementation change. Results in new or modified code, protocol definitions, or CRDs.

Informational

Provides guidelines, background, or describes an issue without proposing a specific change. Does not require community consensus to adopt.

Process

Proposes a change to the Jumpstarter development process, governance, or workflow (like this JEP).

JEP Lifecycle

        flowchart TD
    A([Start]) --> B[Draft]
    B -->|PR opened| C[Discussion]
    C -->|Maintainers approve| D[Accepted]
    C -->|Maintainers decline| E[Rejected]
    D -->|Work begins| F[Implementing]
    F -->|Code merged| G[Implemented]
    G -->|Stabilized| H[Final]
    F -->|Deprioritized| I[Deferred]
    D -->|Deprioritized| I
    I -.->|Revisited| C

Note: A JEP can move to Withdrawn from any pre-Final status (at the author’s discretion) and to Superseded from any status (when replaced by a newer JEP). These transitions are omitted from the diagram for clarity.

Status

Meaning

Draft

Author is still writing the JEP. Not yet open for formal review.

Discussion

JEP PR is open and under community discussion.

Accepted

Maintainers have approved the design. Implementation may begin.

Implementing

Implementation is in progress. The JEP may be updated with implementation learnings.

Implemented

Reference implementation is complete and merged.

Final

JEP is complete and considered the authoritative record of the feature.

Rejected

Maintainers have declined the proposal. The JEP remains as a record of the decision.

Deferred

Proposal is sound but not a current priority. May be revisited later.

Withdrawn

Author has voluntarily withdrawn the proposal.

Active

Living document, actively maintained and updated as the process evolves. Used only for Process JEPs.

Superseded

Replaced by a newer JEP. The Superseded-By field indicates the replacement.

A JEP can move to Withdrawn from any pre-Final status. A JEP can move to Superseded from any status.

JEP Workflow

1. Socialize the Idea

Before writing a JEP, discuss the idea informally:

  • Start a thread in Matrix.

  • Add it to the agenda for the weekly meeting.

  • Open a GitHub issue labeled jep/discussion for early feedback.

This step helps determine whether a JEP is warranted, identifies potential reviewers, and surfaces obvious concerns early.

2. Submit a JEP Pull Request

Create a new branch and add your JEP as a markdown file in the python/docs/source/internal/jeps/ directory, following the JEP template. Open a pull request against the main branch. The PR-based workflow makes discussion easier through inline review comments and suggested changes.

The JEP title should follow the format:

JEP: Short descriptive title

The JEP number is an incrementing integer assigned sequentially (e.g., JEP-0010, JEP-0011, JEP-0012). It is not derived from the PR number. To determine the next available number, check the existing JEPs in the python/docs/source/internal/jeps/ directory and increment from the highest existing number. Apply the jep label to the pull request.

Fill in every section of the template. Sections marked (Optional) may be omitted if not applicable, but all required sections must be present. Set the JEP status to Discussion when the PR is ready for review.

3. Discussion and Revision

The community reviews the JEP on the pull request. PRs are the preferred venue for discussion, as they allow inline review comments on the JEP text itself. The author is expected to:

  • Respond to feedback and revise the JEP accordingly.

  • Build consensus, especially among contributors who would be affected by the change.

  • Document dissenting opinions in the Rejected Alternatives section.

4. Decision

Jumpstarter maintainers make the final decision to accept or reject a JEP. Decisions are recorded as a comment on the pull request with a rationale. The author updates the JEP status in the markdown file.

JEPs should always be merged as PRs so the markdown documentation is incorporated directly into the Jumpstarter docs/source. Rejected JEPs are normally not merged as PRs. However, if there is an architectural reason to preserve a rejected JEP in the repository (e.g., to document why an approach was not taken for future reference), it may be merged with a Rejected status clearly set in the metadata.

5. Implementation

Once accepted, the author (or any willing contributor) implements the feature. Implementation PRs should reference the JEP (e.g., Implements JEP-0400). The JEP’s Implementation History section should be updated with links to relevant PRs as they are merged. The JEP moves through Implementing → Implemented → Final as work progresses.

Roles

Role

Responsibility

Author

Writes the JEP, responds to feedback, shepherds the proposal through the process.

Reviewer

Provides technical feedback on the pull request. Any community member can review.

Maintainer

Makes the final accept/reject decision. Must provide written rationale.

Implementer

Writes the code. Often the author, but doesn’t have to be.

JEP Numbering

JEP numbers are incrementing integers assigned sequentially. They are not derived from the pull request number. Once assigned, a JEP number is never reused. JEP-0000 through JEP-0009 are reserved for process and meta-JEPs.

JEP Index

The file python/docs/source/internal/jeps/README.md serves as the index of all JEPs. Alternatively, all JEPs can be found by filtering GitHub pull requests with the jep label.

Amendments to This Process

Changes to the JEP process itself require a new Process-type JEP.

Prior Art

This process draws inspiration from:

  • Python Enhancement Proposals (PEPs) — lightweight metadata, champion model, clear status lifecycle.

  • Kubernetes Enhancement Proposals (KEPs) — test plan requirements, graduation criteria, production readiness.

  • Rust RFCs — PR-based workflow, emphasis on motivation and teaching, prior art section.

  • Architecture Decision Records (ADRs) — structured decision documentation with context, alternatives, and consequences. The JEP template adopts the ADR pattern for individual design decisions.

  • GitHub SpecKit — spec-driven development methodology with structured templates and agent-friendly document conventions. The JEP template adopts SpecKit’s practice of marking sections as mandatory or optional and structuring documents for machine readability.