Add Jumpstarter Enhancement Proposal (JEP) Process and Issue Template

.claude/rules/jep-adr-process.md

@@ -0,0 +1 @@
+../../.cursor/rules/jep-adr-process.mdc

.claude/skills/propose-jep/SKILL.md

@@ -0,0 +1 @@
+../../../.cursor/skills/propose-jep/SKILL.md

.cursor/rules/jep-adr-process.mdc

@@ -0,0 +1,62 @@
+---
+alwaysApply: false
+---
+
+# JEP Process
+
+This rule helps with creating Jumpstarter Enhancement Proposals (JEPs).
+
+## When to Use
+
+- **JEP**: Cross-cutting changes that affect multiple components, change public APIs or protocols, or require community consensus.
+
+## Creating a JEP
+
+1. **Choose the next JEP number**: Look at existing files in `python/docs/source/internal/jeps/` and pick the next available incrementing integer. JEP-0000 through JEP-0009 are reserved for process/meta-JEPs, so start from JEP-0010 for regular proposals.
+
+2. **Create the file**: Copy the template from `python/docs/source/internal/jeps/JEP-NNNN-template.md` to `python/docs/source/internal/jeps/JEP-NNNN-short-title.md`, replacing `NNNN` with the zero-padded number and `short-title` with a descriptive slug.
+
+3. **Fill in the metadata table**:
+   - Set the JEP number (incrementing integer, NOT the PR number)
+   - Set the title, author(s) with GitHub handle and email
+   - Set the type: `Standards Track`, `Informational`, or `Process`
+   - Set the status to `Draft` initially, then `Discussion` when the PR is ready for review
+   - Set the created date to today
+
+4. **Fill in all mandatory sections**:
+   - Abstract (3-5 sentences)
+   - Motivation (concrete problem description)
+   - Proposal (written as if teaching the feature)
+   - Design Decisions (use DD-N pattern with alternatives and rationale)
+   - Design Details (architecture, data flow, error handling)
+   - Test Plan (unit, integration, HiL, manual)
+   - Backward Compatibility
+   - Consequences (positive and negative)
+   - Rejected Alternatives
+
+5. **Open a PR** against main with the `jep` label.
+
+## Design Decision Format (DD-N)
+
+JEPs use this format for individual decisions:
+
+```markdown
+### DD-N: Decision title
+
+**Alternatives considered:**
+
+1. **Option A** — Brief description.
+2. **Option B** — Brief description.
+
+**Decision:** Option A.
+
+**Rationale:** Explain why this option was chosen.
+```
+
+## Key Rules
+
+- JEP numbers are incrementing integers, NOT derived from PR numbers
+- JEPs live in `python/docs/source/internal/jeps/`
+- All JEPs should be merged as PRs so the documentation is part of the Jumpstarter docs/source
+- Rejected JEPs are normally not merged, but can be merged with "Rejected" status if there is an architectural reason to preserve them
+- The license for all documents is Apache-2.0

.cursor/rules/project-structure.mdc

@@ -14,7 +14,10 @@ jumpstarter/
 │   ├── pyproject.toml      # Main workspace configuration
 │   ├── packages/           # All Python packages
 │   ├── examples/           # Example applications
-│   ├── docs/               # Documentation
+│   ├── docs/               # Documentation (Sphinx)
+│   │   └── source/
+│   │       └── internal/   # JEPs (rendered as part of docs)
+│   │           └── jeps/   # Jumpstarter Enhancement Proposals
 │   └── __templates__/      # Templates for creating new drivers
 ├── controller/             # Controller components
 ├── protocol/               # Protocol definitions

.cursor/skills/propose-jep/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: propose-jep
+description: Create a new Jumpstarter Enhancement Proposal (JEP)
+argument-hint: Short title or description of the proposal
+---
+
+# Propose a JEP
+
+You are helping the user create a new Jumpstarter Enhancement Proposal (JEP).
+
+## Context
+
+JEPs are design documents for substantial changes to the Jumpstarter project — changes that affect multiple components, alter public APIs or protocols, or require community consensus. Read `.cursor/rules/jep-adr-process.mdc` for the full process definition.
+
+JEP topic: $ARGUMENTS
+
+## Steps
+
+### 1. Determine the next JEP number
+
+List existing files in `python/docs/source/internal/jeps/` and pick the next available incrementing integer. JEP-0000 through JEP-0009 are reserved for process/meta-JEPs, so start from JEP-0010 for regular proposals.
+
+### 2. Gather information
+
+Before writing the JEP, ask the user clarifying questions to understand:
+
+- **What problem does this solve?** — The motivation section needs a concrete problem description.
+- **Who is affected?** — Which components, drivers, or user workflows are impacted?
+- **What are the alternatives?** — Each design decision needs at least two alternatives considered.
+- **What are the compatibility implications?** — Does this break existing APIs, protocols, or workflows?
+
+If the user provided a description in `$ARGUMENTS`, use it as a starting point but still ask about gaps.
+
+### 3. Create the JEP file
+
+Copy the template from `python/docs/source/internal/jeps/JEP-NNNN-template.md` and create a new file at `python/docs/source/internal/jeps/JEP-NNNN-short-title.md` where:
+
+- `NNNN` is the zero-padded next number
+- `short-title` is a descriptive slug derived from the proposal title
+
+Fill in:
+
+- The metadata table with the JEP number, title, author (ask the user), status `Draft`, type, and today's date
+- All mandatory sections based on the information gathered
+- Mark optional sections that need further input with TODO comments
+
+### 4. Update the JEP index
+
+Add the new JEP to the appropriate table in `python/docs/source/internal/jeps/README.md` (Process, Standards Track, or Informational).
+
+Add the new JEP file to the `{toctree}` directive at the bottom of `python/docs/source/internal/jeps/README.md`.
+
+### 5. Present the result
+
+Show the user:
+
+- The file path of the new JEP
+- A summary of sections that are complete vs need further work
+- Remind them to set status to `Discussion` when the PR is ready for review
+- Remind them to apply the `jep` label to their pull request

python/docs/source/index.md

@@ -59,4 +59,5 @@ contributing.md
 glossary.md
 
 reference/index.md
-```
+internal/index.md
+```

python/docs/source/internal/index.md

@@ -0,0 +1,11 @@
+# Project Governance
+
+This section contains Jumpstarter Enhancement Proposals (JEPs) that document
+significant design decisions and process changes.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+jeps/README.md
+```

python/docs/source/internal/jeps/JEP-0000-jep-process.md

@@ -0,0 +1,234 @@
+# 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](https://github.com/jumpstarter-dev/jumpstarter/pull/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](https://matrix.to/#/#jumpstarter:matrix.org) 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
+
+```{mermaid}
+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](https://matrix.to/#/#jumpstarter:matrix.org).
+- Add it to the agenda for the [weekly meeting](https://meet.google.com/gzd-hhbd-hpu).
+- 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](JEP-NNNN-template.md). 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:
+
+```text
+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)](https://peps.python.org/pep-0001/) —
+  lightweight metadata, champion model, clear status lifecycle.
+- [Kubernetes Enhancement Proposals (KEPs)](https://github.com/kubernetes/enhancements/tree/master/keps) —
+  test plan requirements, graduation criteria, production readiness.
+- [Rust RFCs](https://github.com/rust-lang/rfcs) — PR-based workflow, emphasis
+  on motivation and teaching, prior art section.
+- [Architecture Decision Records (ADRs)](https://adr.github.io/) — structured
+  decision documentation with context, alternatives, and consequences. The JEP
+  template adopts the ADR pattern for individual design decisions.
+- [GitHub SpecKit](https://github.com/github/spec-kit) — 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.
+
+## Copyright
+
+This document is placed under the
+[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0),
+consistent with the Jumpstarter project license.