From 213936a6831ca36d9fe1882c33035d54ba2da2ee Mon Sep 17 00:00:00 2001 From: Kirk Brauer Date: Tue, 7 Apr 2026 11:48:39 -0400 Subject: [PATCH 01/13] Add Jumpstarter Enhancement Proposal (JEP) process and issue template --- .github/ISSUE_TEMPLATE/jep-proposal.yml | 190 +++++++++++++++++++ jep/JEP-0000-jep-process.md | 225 +++++++++++++++++++++++ jep/JEP-NNNN-template.md | 231 ++++++++++++++++++++++++ jep/README.md | 59 ++++++ 4 files changed, 705 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/jep-proposal.yml create mode 100644 jep/JEP-0000-jep-process.md create mode 100644 jep/JEP-NNNN-template.md create mode 100644 jep/README.md diff --git a/.github/ISSUE_TEMPLATE/jep-proposal.yml b/.github/ISSUE_TEMPLATE/jep-proposal.yml new file mode 100644 index 000000000..0d47739a7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/jep-proposal.yml @@ -0,0 +1,190 @@ +name: "JEP: Enhancement Proposal" +description: Propose a substantial change to the Jumpstarter project +title: "JEP: " +labels: ["jep"] +body: + - type: markdown + attributes: + value: | + # Jumpstarter Enhancement Proposal (JEP) + + Use this template to propose substantial changes to Jumpstarter. + See [JEP-0000](https://github.com/jumpstarter-dev/jumpstarter/blob/main/jeps/JEP-0000-jep-process.md) for when a JEP is needed and the full process. + + **Tip:** Not every change needs a JEP. Bug fixes, new drivers following existing patterns, docs improvements, and dependency bumps should use a regular issue or PR instead. + + - type: dropdown + id: type + attributes: + label: JEP Type + options: + - Standards Track (new feature or implementation change) + - Informational (guidelines or background) + - Process (development process or governance change) + validations: + required: true + + - type: dropdown + id: status + attributes: + label: Status + description: Set to "Proposed" when this issue is ready for review + options: + - Draft + - Proposed + default: 0 + validations: + required: true + + - type: textarea + id: abstract + attributes: + label: Abstract + description: One paragraph (3-5 sentences) summarizing the proposal + placeholder: A reader should be able to decide whether this JEP is relevant to them from the abstract alone. + validations: + required: true + + - type: textarea + id: motivation + attributes: + label: Motivation + description: | + Why is this change needed? What problem does it solve? Who benefits? + Describe the problem in concrete terms. Include specific scenarios that Jumpstarter users, driver authors, or operators encounter today. Do not describe the solution here. + placeholder: | + Describe the problem, not the solution. + + ### User Stories (optional) + - **As a** CI pipeline author, **I want to** ..., **so that** ... + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposal + description: | + Explain the proposal as if it were already implemented and you are teaching it to another Jumpstarter contributor. + Show CLI commands, config files, Python API calls, YAML manifests, etc. + placeholder: | + Introduce new concepts by name. Use code examples and diagrams where they help. + + ### API / Protocol Changes (if applicable) + Show before/after of any changed message types, RPCs, or CRD fields. + + ### Hardware Considerations (if applicable) + What hardware is required or affected? Timing constraints? Privilege requirements? + validations: + required: true + + - type: textarea + id: design-details + attributes: + label: Design Details + description: | + The technical heart of the JEP. Cover architecture, data flow, error handling, concurrency, and security implications. + placeholder: Use diagrams (Mermaid, ASCII art) for complex interactions. + validations: + required: true + + - type: textarea + id: test-plan + attributes: + label: Test Plan + description: How will this feature be tested? + placeholder: | + ### Unit Tests + What can be tested in isolation without hardware? + + ### Integration Tests + What requires a running Jumpstarter environment? + + ### Hardware-in-the-Loop Tests + What requires physical hardware? Specify the hardware needed. + + ### Manual Verification + What requires manual testing? + validations: + required: true + + - type: textarea + id: backward-compatibility + attributes: + label: Backward Compatibility + description: | + Does this change break existing users, drivers, exporters, or deployments? + What is the migration path? + placeholder: Describe impact on existing deployments, wire format compatibility, operator upgrade path, etc. + validations: + required: true + + - type: textarea + id: rejected-alternatives + attributes: + label: Rejected Alternatives + description: What other designs were considered and why were they not chosen? + placeholder: This section helps future contributors understand why the chosen approach was preferred. + validations: + required: true + + - type: textarea + id: graduation-criteria + attributes: + label: Graduation Criteria + description: For features introduced incrementally (behind a feature flag, as experimental, etc.) + placeholder: | + ### Experimental + What signals indicate readiness for broader testing? + + ### Stable + What criteria must be met before removing the experimental designation? + validations: + required: false + + - type: textarea + id: prior-art + attributes: + label: Prior Art + description: Are similar features present in other HiL frameworks, testing tools, or infrastructure projects? + placeholder: "Consider: dSPACE, NI TestStand, LAVA, Robot Framework, pytest-embedded, Kubernetes patterns, etc." + validations: + required: false + + - type: textarea + id: unresolved-questions + attributes: + label: Unresolved Questions + description: What aspects of the design are still open? + placeholder: List specific questions to be resolved during the JEP review process. + validations: + required: false + + - type: textarea + id: future-possibilities + attributes: + label: Future Possibilities + description: What natural extensions or follow-up work does this proposal enable? + placeholder: Be explicit that these are NOT part of the current proposal. + validations: + required: false + + - type: textarea + id: implementation-history + attributes: + label: Implementation History + description: Updated as the implementation progresses + placeholder: | + - YYYY-MM-DD: JEP proposed (this issue) + - YYYY-MM-DD: JEP accepted + - YYYY-MM-DD: Initial implementation merged (PR #NNN) + validations: + required: false + + - type: textarea + id: references + attributes: + label: References + description: Links to related issues, PRs, external docs, or discussions + validations: + required: false diff --git a/jep/JEP-0000-jep-process.md b/jep/JEP-0000-jep-process.md new file mode 100644 index 000000000..236571810 --- /dev/null +++ b/jep/JEP-0000-jep-process.md @@ -0,0 +1,225 @@ +# 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** | [Matrix](https://matrix.to/#/#jumpstarter:matrix.org) | + +## 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[Proposed] + 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. | +| **Proposed** | 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. | +| **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. Open a JEP Issue + +Open a new issue in the +[jumpstarter-dev/jumpstarter](https://github.com/jumpstarter-dev/jumpstarter) +repository using the **JEP Proposal** issue template. The template mirrors +the structure of the JEP and will prompt you to fill in each section. + +The issue title should follow the format: + +``` +JEP: Short descriptive title +``` + +The issue number automatically becomes the JEP number (e.g., issue #400 +becomes JEP-0400). Apply the `jep` label to the issue. + +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 **Proposed** when the issue is ready for review. + +### 3. Discussion and Revision + +The community reviews the JEP directly on the GitHub issue. The author is +expected to: + +- Respond to feedback and revise the JEP body accordingly. +- Build consensus, especially among contributors who would be affected by the + change. +- Document dissenting opinions in the **Rejected Alternatives** section. + +GitHub issues provide better threading for discussion than PRs, and allow +anyone — including non-developers — to participate without needing to fork +the repository. + +### 4. Decision + +Jumpstarter maintainers make the final decision to accept or reject a JEP. +Decisions are recorded as a comment on the issue with a rationale. The author +updates the JEP status in the issue body. Rejected JEPs are closed but not +deleted — they remain as the historical record of why an approach was not +taken. + +### 5. Implementation + +Once accepted, the author (or any willing contributor) implements the feature. +Implementation PRs should reference the JEP issue (e.g., `Implements JEP-0400`). +The JEP issue'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. The issue is closed when the JEP +reaches **Final** status. + +## Roles + +| Role | Responsibility | +|-----------------|----------------------------------------------------------------------------------------------| +| **Author** | Writes the JEP, responds to feedback, shepherds the proposal through the process. | +| **Reviewer** | Provides technical feedback on the issue. 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 assigned from the GitHub issue number used to submit the JEP. +Once assigned, a JEP number is never reused. JEP-0000 through JEP-0009 are +reserved for process and meta-JEPs. + +Existing enhancement issues that predate the JEP process may be retroactively +adopted as JEPs by updating the issue body to follow the JEP template and +applying the `jep` label. + +## JEP Index + +The file `jeps/README.md` serves as the index of all JEPs. Alternatively, +all JEPs can be found by filtering GitHub issues 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. + +## 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. diff --git a/jep/JEP-NNNN-template.md b/jep/JEP-NNNN-template.md new file mode 100644 index 000000000..10f36688c --- /dev/null +++ b/jep/JEP-NNNN-template.md @@ -0,0 +1,231 @@ +# JEP-NNNN: Your Short, Descriptive Title + + + +| Field | Value | +|--------------------|--------------------------------------------| +| **JEP** | NNNN *(replaced with issue number)* | +| **Title** | *Your short, descriptive title* | +| **Author(s)** | *@github-handle (Full Name \)* | +| **Status** | Draft | +| **Type** | Standards Track \| Informational \| Process | +| **Created** | *YYYY-MM-DD* | +| **Updated** | *YYYY-MM-DD* | +| **Discussion** | *Link to Matrix thread or GitHub issue* | +| **Requires** | *JEP-NNNN (if depends on another JEP)* | +| **Supersedes** | *JEP-NNNN (if replacing a previous JEP)* | +| **Superseded-By** | *JEP-NNNN (filled in later if applicable)* | + +--- + +## Abstract + + + +## Motivation + + + +### User Stories (Optional) + + + +## Proposal + + + +### API / Protocol Changes (if applicable) + + + +### Hardware Considerations (if applicable) + + + +## Design Details + + + +## Test Plan + + + +## Graduation Criteria (Optional) + + + +## Backward Compatibility + + + +## Rejected Alternatives + + + +## Prior Art (Optional) + + + +## Unresolved Questions + + + +## Future Possibilities (Optional) + + + +## Implementation History + + + +## References + + + +--- + +*This JEP is licensed under the +[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), +consistent with the Jumpstarter project.* diff --git a/jep/README.md b/jep/README.md new file mode 100644 index 000000000..55e197308 --- /dev/null +++ b/jep/README.md @@ -0,0 +1,59 @@ +# Jumpstarter Enhancement Proposals (JEPs) + +This directory contains the Jumpstarter Enhancement Proposals — design documents +that describe significant changes to the Jumpstarter project. + +## What is a JEP? + +A JEP is a design document that proposes a new feature, process change, or +architectural decision for the Jumpstarter hardware-in-the-loop testing +framework. JEPs provide a transparent, structured process for the community to +propose, discuss, and decide on substantial changes. + +For the full process definition, see [JEP-0000](JEP-0000-jep-process.md). + +## Quick Start + +1. Read [JEP-0000](JEP-0000-jep-process.md) to understand when a JEP is needed. +2. Socialize your idea in [Matrix](https://matrix.to/#/#jumpstarter:matrix.org) + or at the [weekly meeting](https://meet.google.com/gzd-hhbd-hpu). +3. Open a new issue using the **JEP: Enhancement Proposal** template. +4. The issue number becomes your JEP number. + +Alternatively, the [JEP-NNNN-template.md](JEP-NNNN-template.md) provides a +markdown reference version of the template for longer-form proposals. + +## JEP Index + +### Process JEPs + +| JEP | Title | Status | Author(s) | +|------|-------------------------------------------|--------|-------------------------| +| 0000 | [JEP Process](JEP-0000-jep-process.md) | Active | Jumpstarter Maintainers | + +### Standards Track JEPs + +| JEP | Title | Status | Author(s) | +|------|-------|--------|-----------| +| *none yet* | | | | + +### Informational JEPs + +| JEP | Title | Status | Author(s) | +|------|-------|--------|-----------| +| *none yet* | | | | + +## Status Key + +| Status | Meaning | +|----------------|------------------------------------------------------| +| Draft | Author is still writing; not yet open for review | +| Proposed | PR is open and under community discussion | +| Accepted | Design approved; implementation may begin | +| Implementing | Implementation in progress | +| Implemented | Reference implementation merged | +| Final | Complete and authoritative | +| Rejected | Declined (record preserved) | +| Deferred | Sound but not a current priority | +| Withdrawn | Author voluntarily withdrew | +| Superseded | Replaced by a newer JEP | From 5a21d8ac906e2aa4b860f1f542470f0ed0542fc2 Mon Sep 17 00:00:00 2001 From: Kirk Brauer Date: Wed, 8 Apr 2026 10:54:52 +0000 Subject: [PATCH 02/13] fix: rename jep/ to jeps/ and address review comments - Rename jep/ directory to jeps/ per maintainer feedback - Add text language specifier to fenced code block - Update workflow to clarify JEPs should be submitted as PRs for discussion Co-Authored-By: Claude Opus 4.6 --- {jep => jeps}/JEP-0000-jep-process.md | 27 ++++++++++++++------------- {jep => jeps}/JEP-NNNN-template.md | 0 {jep => jeps}/README.md | 10 ++++++---- 3 files changed, 20 insertions(+), 17 deletions(-) rename {jep => jeps}/JEP-0000-jep-process.md (93%) rename {jep => jeps}/JEP-NNNN-template.md (100%) rename {jep => jeps}/README.md (84%) diff --git a/jep/JEP-0000-jep-process.md b/jeps/JEP-0000-jep-process.md similarity index 93% rename from jep/JEP-0000-jep-process.md rename to jeps/JEP-0000-jep-process.md index 236571810..778752c91 100644 --- a/jep/JEP-0000-jep-process.md +++ b/jeps/JEP-0000-jep-process.md @@ -128,16 +128,20 @@ Before writing a JEP, discuss the idea informally: This step helps determine whether a JEP is warranted, identifies potential reviewers, and surfaces obvious concerns early. -### 2. Open a JEP Issue +### 2. Submit a JEP Pull Request -Open a new issue in the -[jumpstarter-dev/jumpstarter](https://github.com/jumpstarter-dev/jumpstarter) -repository using the **JEP Proposal** issue template. The template mirrors +Create a new branch and add your JEP as a markdown file in the `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. + +You may also open a GitHub issue using the **JEP Proposal** issue template +for initial discussion or lightweight proposals. The issue template mirrors the structure of the JEP and will prompt you to fill in each section. -The issue title should follow the format: +The JEP title should follow the format: -``` +```text JEP: Short descriptive title ``` @@ -150,18 +154,15 @@ the JEP status to **Proposed** when the issue is ready for review. ### 3. Discussion and Revision -The community reviews the JEP directly on the GitHub issue. The author is -expected to: +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 body accordingly. +- 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. -GitHub issues provide better threading for discussion than PRs, and allow -anyone — including non-developers — to participate without needing to fork -the repository. - ### 4. Decision Jumpstarter maintainers make the final decision to accept or reject a JEP. diff --git a/jep/JEP-NNNN-template.md b/jeps/JEP-NNNN-template.md similarity index 100% rename from jep/JEP-NNNN-template.md rename to jeps/JEP-NNNN-template.md diff --git a/jep/README.md b/jeps/README.md similarity index 84% rename from jep/README.md rename to jeps/README.md index 55e197308..f1dbdd3ca 100644 --- a/jep/README.md +++ b/jeps/README.md @@ -17,11 +17,13 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md). 1. Read [JEP-0000](JEP-0000-jep-process.md) to understand when a JEP is needed. 2. Socialize your idea in [Matrix](https://matrix.to/#/#jumpstarter:matrix.org) or at the [weekly meeting](https://meet.google.com/gzd-hhbd-hpu). -3. Open a new issue using the **JEP: Enhancement Proposal** template. -4. The issue number becomes your JEP number. +3. Create a branch and add your JEP markdown file to the `jeps/` directory + using the [JEP-NNNN-template.md](JEP-NNNN-template.md) as a starting point. +4. Open a pull request. The PR serves as the primary venue for discussion, + allowing inline review comments on the JEP text. -Alternatively, the [JEP-NNNN-template.md](JEP-NNNN-template.md) provides a -markdown reference version of the template for longer-form proposals. +You may also open a GitHub issue using the **JEP: Enhancement Proposal** +template for initial discussion or lightweight proposals. ## JEP Index From a323b3f5ae69aa261ff3f294953ab111db9348cb Mon Sep 17 00:00:00 2001 From: Kirk Brauer Date: Wed, 8 Apr 2026 15:53:30 +0000 Subject: [PATCH 03/13] Remove issue template and standardize JEP process on PRs Remove the JEP proposal issue template and update all JEP documentation to reference pull requests as the sole mechanism for submitting formal proposals. This simplifies the process by having a single, consistent workflow for JEP submission and review. Co-Authored-By: Claude Opus 4.6 --- .github/ISSUE_TEMPLATE/jep-proposal.yml | 190 ------------------------ jeps/JEP-0000-jep-process.md | 35 ++--- jeps/JEP-NNNN-template.md | 11 +- jeps/README.md | 3 - 4 files changed, 17 insertions(+), 222 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/jep-proposal.yml diff --git a/.github/ISSUE_TEMPLATE/jep-proposal.yml b/.github/ISSUE_TEMPLATE/jep-proposal.yml deleted file mode 100644 index 0d47739a7..000000000 --- a/.github/ISSUE_TEMPLATE/jep-proposal.yml +++ /dev/null @@ -1,190 +0,0 @@ -name: "JEP: Enhancement Proposal" -description: Propose a substantial change to the Jumpstarter project -title: "JEP: " -labels: ["jep"] -body: - - type: markdown - attributes: - value: | - # Jumpstarter Enhancement Proposal (JEP) - - Use this template to propose substantial changes to Jumpstarter. - See [JEP-0000](https://github.com/jumpstarter-dev/jumpstarter/blob/main/jeps/JEP-0000-jep-process.md) for when a JEP is needed and the full process. - - **Tip:** Not every change needs a JEP. Bug fixes, new drivers following existing patterns, docs improvements, and dependency bumps should use a regular issue or PR instead. - - - type: dropdown - id: type - attributes: - label: JEP Type - options: - - Standards Track (new feature or implementation change) - - Informational (guidelines or background) - - Process (development process or governance change) - validations: - required: true - - - type: dropdown - id: status - attributes: - label: Status - description: Set to "Proposed" when this issue is ready for review - options: - - Draft - - Proposed - default: 0 - validations: - required: true - - - type: textarea - id: abstract - attributes: - label: Abstract - description: One paragraph (3-5 sentences) summarizing the proposal - placeholder: A reader should be able to decide whether this JEP is relevant to them from the abstract alone. - validations: - required: true - - - type: textarea - id: motivation - attributes: - label: Motivation - description: | - Why is this change needed? What problem does it solve? Who benefits? - Describe the problem in concrete terms. Include specific scenarios that Jumpstarter users, driver authors, or operators encounter today. Do not describe the solution here. - placeholder: | - Describe the problem, not the solution. - - ### User Stories (optional) - - **As a** CI pipeline author, **I want to** ..., **so that** ... - validations: - required: true - - - type: textarea - id: proposal - attributes: - label: Proposal - description: | - Explain the proposal as if it were already implemented and you are teaching it to another Jumpstarter contributor. - Show CLI commands, config files, Python API calls, YAML manifests, etc. - placeholder: | - Introduce new concepts by name. Use code examples and diagrams where they help. - - ### API / Protocol Changes (if applicable) - Show before/after of any changed message types, RPCs, or CRD fields. - - ### Hardware Considerations (if applicable) - What hardware is required or affected? Timing constraints? Privilege requirements? - validations: - required: true - - - type: textarea - id: design-details - attributes: - label: Design Details - description: | - The technical heart of the JEP. Cover architecture, data flow, error handling, concurrency, and security implications. - placeholder: Use diagrams (Mermaid, ASCII art) for complex interactions. - validations: - required: true - - - type: textarea - id: test-plan - attributes: - label: Test Plan - description: How will this feature be tested? - placeholder: | - ### Unit Tests - What can be tested in isolation without hardware? - - ### Integration Tests - What requires a running Jumpstarter environment? - - ### Hardware-in-the-Loop Tests - What requires physical hardware? Specify the hardware needed. - - ### Manual Verification - What requires manual testing? - validations: - required: true - - - type: textarea - id: backward-compatibility - attributes: - label: Backward Compatibility - description: | - Does this change break existing users, drivers, exporters, or deployments? - What is the migration path? - placeholder: Describe impact on existing deployments, wire format compatibility, operator upgrade path, etc. - validations: - required: true - - - type: textarea - id: rejected-alternatives - attributes: - label: Rejected Alternatives - description: What other designs were considered and why were they not chosen? - placeholder: This section helps future contributors understand why the chosen approach was preferred. - validations: - required: true - - - type: textarea - id: graduation-criteria - attributes: - label: Graduation Criteria - description: For features introduced incrementally (behind a feature flag, as experimental, etc.) - placeholder: | - ### Experimental - What signals indicate readiness for broader testing? - - ### Stable - What criteria must be met before removing the experimental designation? - validations: - required: false - - - type: textarea - id: prior-art - attributes: - label: Prior Art - description: Are similar features present in other HiL frameworks, testing tools, or infrastructure projects? - placeholder: "Consider: dSPACE, NI TestStand, LAVA, Robot Framework, pytest-embedded, Kubernetes patterns, etc." - validations: - required: false - - - type: textarea - id: unresolved-questions - attributes: - label: Unresolved Questions - description: What aspects of the design are still open? - placeholder: List specific questions to be resolved during the JEP review process. - validations: - required: false - - - type: textarea - id: future-possibilities - attributes: - label: Future Possibilities - description: What natural extensions or follow-up work does this proposal enable? - placeholder: Be explicit that these are NOT part of the current proposal. - validations: - required: false - - - type: textarea - id: implementation-history - attributes: - label: Implementation History - description: Updated as the implementation progresses - placeholder: | - - YYYY-MM-DD: JEP proposed (this issue) - - YYYY-MM-DD: JEP accepted - - YYYY-MM-DD: Initial implementation merged (PR #NNN) - validations: - required: false - - - type: textarea - id: references - attributes: - label: References - description: Links to related issues, PRs, external docs, or discussions - validations: - required: false diff --git a/jeps/JEP-0000-jep-process.md b/jeps/JEP-0000-jep-process.md index 778752c91..6a5178fbb 100644 --- a/jeps/JEP-0000-jep-process.md +++ b/jeps/JEP-0000-jep-process.md @@ -135,22 +135,18 @@ 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. -You may also open a GitHub issue using the **JEP Proposal** issue template -for initial discussion or lightweight proposals. The issue template mirrors -the structure of the JEP and will prompt you to fill in each section. - The JEP title should follow the format: ```text JEP: Short descriptive title ``` -The issue number automatically becomes the JEP number (e.g., issue #400 -becomes JEP-0400). Apply the `jep` label to the issue. +The PR number becomes the JEP number (e.g., PR #400 becomes JEP-0400). +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 **Proposed** when the issue is ready for review. +the JEP status to **Proposed** when the PR is ready for review. ### 3. Discussion and Revision @@ -166,43 +162,38 @@ itself. The author is expected to: ### 4. Decision Jumpstarter maintainers make the final decision to accept or reject a JEP. -Decisions are recorded as a comment on the issue with a rationale. The author -updates the JEP status in the issue body. Rejected JEPs are closed but not -deleted — they remain as the historical record of why an approach was not -taken. +Decisions are recorded as a comment on the pull request with a rationale. The +author updates the JEP status in the markdown file. Rejected JEPs are closed +but not deleted — they remain as the historical record of why an approach was +not taken. ### 5. Implementation Once accepted, the author (or any willing contributor) implements the feature. -Implementation PRs should reference the JEP issue (e.g., `Implements JEP-0400`). -The JEP issue's **Implementation History** section should be updated with links +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. The issue is closed when the JEP -reaches **Final** status. +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 issue. Any community member can review. | +| **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 assigned from the GitHub issue number used to submit the JEP. +JEP numbers are assigned from the pull request number used to submit the JEP. Once assigned, a JEP number is never reused. JEP-0000 through JEP-0009 are reserved for process and meta-JEPs. -Existing enhancement issues that predate the JEP process may be retroactively -adopted as JEPs by updating the issue body to follow the JEP template and -applying the `jep` label. - ## JEP Index The file `jeps/README.md` serves as the index of all JEPs. Alternatively, -all JEPs can be found by filtering GitHub issues with the `jep` label. +all JEPs can be found by filtering GitHub pull requests with the `jep` label. ## Amendments to This Process diff --git a/jeps/JEP-NNNN-template.md b/jeps/JEP-NNNN-template.md index 10f36688c..3dd540518 100644 --- a/jeps/JEP-NNNN-template.md +++ b/jeps/JEP-NNNN-template.md @@ -1,12 +1,9 @@ # JEP-NNNN: Your Short, Descriptive Title | Field | Value | @@ -28,14 +32,14 @@ --- -## Abstract +## Abstract *(mandatory)* -## Motivation +## Motivation *(mandatory)* -### User Stories (Optional) +### User Stories *(optional)* -## Proposal +## Proposal *(mandatory)* -### API / Protocol Changes (if applicable) +### API / Protocol Changes *(if applicable)* -### Hardware Considerations (if applicable) +### Hardware Considerations *(if applicable)* -## Design Details +## Design Decisions *(mandatory for Standards Track)* + + + +### DD-1: *Decision title* + +**Alternatives considered:** + +1. **Option A** — Brief description. +2. **Option B** — Brief description. + +**Decision:** Option A. + +**Rationale:** Explain why this option was chosen over the alternatives. +Reference specific project constraints, prior art, or technical tradeoffs. + + + +## Design Details *(mandatory for Standards Track)* -## Test Plan +## Test Plan *(mandatory for Standards Track)* -## Graduation Criteria (Optional) +## Graduation Criteria *(optional)* -## Backward Compatibility +## Backward Compatibility *(mandatory for Standards Track)* -## Rejected Alternatives +## Consequences *(mandatory)* + + + +### Positive + + + +### Negative + + + +### Risks *(optional)* + + + +## Rejected Alternatives *(mandatory)* -## Prior Art (Optional) +## Prior Art *(optional)* -## Unresolved Questions +## Unresolved Questions *(optional)* -## Future Possibilities (Optional) +## Future Possibilities *(optional)* B[Draft] B -->|PR opened| C[Proposed] @@ -122,18 +122,18 @@ flowchart TD > (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. | -| **Proposed** | 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. | -| **Superseded** | Replaced by a newer JEP. The `Superseded-By` field indicates the replacement. | +| Status | Meaning | +| ---------------- | ------------------------------------------------------------------------------------ | +| **Draft** | Author is still writing the JEP. Not yet open for formal review. | +| **Proposed** | 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. | +| **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. @@ -208,12 +208,12 @@ 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. | +| 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 diff --git a/python/docs/source/internal/jeps/JEP-0010-renode-integration.md b/python/docs/source/internal/jeps/JEP-0010-renode-integration.md index 56a7f3e8a..859d4fbbf 100644 --- a/python/docs/source/internal/jeps/JEP-0010-renode-integration.md +++ b/python/docs/source/internal/jeps/JEP-0010-renode-integration.md @@ -1,15 +1,15 @@ # JEP-0010: Renode Integration for Microcontroller Targets -| Field | Value | -|--------------------|----------------------------------------------| -| **JEP** | 0010 | -| **Title** | Renode Integration for Microcontroller Targets | -| **Author(s)** | @vtz (Vinicius Zein) | -| **Status** | Implemented | -| **Type** | Standards Track | -| **Created** | 2026-04-06 | -| **Updated** | 2026-04-15 | -| **Discussion** | [PR #533](https://github.com/jumpstarter-dev/jumpstarter/pull/533) | +| Field | Value | +| -------------- | ------------------------------------------------------------------ | +| **JEP** | 0010 | +| **Title** | Renode Integration for Microcontroller Targets | +| **Author(s)** | @vtz (Vinicius Zein) | +| **Status** | Implemented | +| **Type** | Standards Track | +| **Created** | 2026-04-06 | +| **Updated** | 2026-04-15 | +| **Discussion** | [PR #533](https://github.com/jumpstarter-dev/jumpstarter/pull/533) | --- diff --git a/python/docs/source/internal/jeps/JEP-NNNN-template.md b/python/docs/source/internal/jeps/JEP-NNNN-template.md index 28dbb5ee7..86c386fc2 100644 --- a/python/docs/source/internal/jeps/JEP-NNNN-template.md +++ b/python/docs/source/internal/jeps/JEP-NNNN-template.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # JEP-NNNN: Your Short, Descriptive Title -| Field | Value | -|--------------------|--------------------------------------------| -| **JEP** | NNNN *(next available incrementing integer)* | -| **Title** | *Your short, descriptive title* | -| **Author(s)** | *@github-handle (Full Name \)* | -| **Status** | Draft | -| **Type** | Standards Track \| Informational \| Process | -| **Created** | *YYYY-MM-DD* | -| **Updated** | *YYYY-MM-DD* | -| **Discussion** | *Link to Matrix thread or GitHub issue* | -| **Requires** | *JEP-NNNN (if depends on another JEP)* | -| **Supersedes** | *JEP-NNNN (if replacing a previous JEP)* | -| **Superseded-By** | *JEP-NNNN (filled in later if applicable)* | +| Field | Value | +| ----------------- | -------------------------------------------- | +| **JEP** | NNNN *(next available incrementing integer)* | +| **Title** | *Your short, descriptive title* | +| **Author(s)** | *@github-handle (Full Name \)* | +| **Status** | Draft | +| **Type** | Standards Track \| Informational \| Process | +| **Created** | *YYYY-MM-DD* | +| **Updated** | *YYYY-MM-DD* | +| **Discussion** | *Link to Matrix thread or GitHub issue* | +| **Requires** | *JEP-NNNN (if depends on another JEP)* | +| **Supersedes** | *JEP-NNNN (if replacing a previous JEP)* | +| **Superseded-By** | *JEP-NNNN (filled in later if applicable)* | --- diff --git a/python/docs/source/internal/jeps/README.md b/python/docs/source/internal/jeps/README.md index 2193da6ee..373c2794b 100644 --- a/python/docs/source/internal/jeps/README.md +++ b/python/docs/source/internal/jeps/README.md @@ -26,21 +26,21 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md). ### Process JEPs -| JEP | Title | Status | Author(s) | -|------|-------------------------------------------|--------|-------------------------| -| 0000 | [JEP Process](JEP-0000-jep-process.md) | Active | Jumpstarter Maintainers | +| JEP | Title | Status | Author(s) | +| ---- | -------------------------------------- | ------ | ----------------------- | +| 0000 | [JEP Process](JEP-0000-jep-process.md) | Active | Jumpstarter Maintainers | ### Standards Track JEPs -| JEP | Title | Status | Author(s) | -|------|-------|--------|-----------| -| *none yet* | | | | +| JEP | Title | Status | Author(s) | +| ---- | ---------------------------------------------------- | ----------- | -------------------- | +| 0010 | [Renode Integration](JEP-0010-renode-integration.md) | Implemented | @vtz (Vinicius Zein) | ### Informational JEPs -| JEP | Title | Status | Author(s) | -|------|-------|--------|-----------| -| *none yet* | | | | +| JEP | Title | Status | Author(s) | +| ---------- | ----- | ------ | --------- | +| *none yet* | | | | ## Related: Architecture Decision Records (ADRs) @@ -52,18 +52,18 @@ guidance on when to use a JEP vs an ADR. ## Status Key -| Status | Meaning | -|----------------|------------------------------------------------------| -| Draft | Author is still writing; not yet open for review | -| Proposed | PR is open and under community discussion | -| Accepted | Design approved; implementation may begin | -| Implementing | Implementation in progress | -| Implemented | Reference implementation merged | -| Final | Complete and authoritative | -| Rejected | Declined (record preserved) | -| Deferred | Sound but not a current priority | -| Withdrawn | Author voluntarily withdrew | -| Superseded | Replaced by a newer JEP | +| Status | Meaning | +| ------------ | ------------------------------------------------ | +| Draft | Author is still writing; not yet open for review | +| Proposed | PR is open and under community discussion | +| Accepted | Design approved; implementation may begin | +| Implementing | Implementation in progress | +| Implemented | Reference implementation merged | +| Final | Complete and authoritative | +| Rejected | Declined (record preserved) | +| Deferred | Sound but not a current priority | +| Withdrawn | Author voluntarily withdrew | +| Superseded | Replaced by a newer JEP | ## For AI Agents @@ -118,4 +118,5 @@ reserved for process and meta-JEPs. :hidden: JEP-0000-jep-process.md +JEP-0010-renode-integration.md ``` From b56b94a3af405d893eb17e3298faf2bf1d2882be Mon Sep 17 00:00:00 2001 From: Kirk Brauer Date: Thu, 16 Apr 2026 14:04:56 +0000 Subject: [PATCH 09/13] Address review feedback on JEP process PR - Replace .claude/rules and .claude/skills copies with symlinks to .cursor/ equivalents, matching the existing convention - Add Acceptance Criteria section to JEP template (mandatory for Standards Track) - Add "Active" status to lifecycle states table in JEP-0000 and README - Fix skill file references to point to .cursor/rules/jep-adr-process.mdc - Add empty toctree directive to ADR index - Simplify "For AI Agents" section in README, defer to agent rule files - Add canonical source note to README status table - Add trailing newline to python/docs/source/index.md - Fix date format inconsistency in JEP-0010 Implementation History Co-Authored-By: Claude Opus 4.6 --- .claude/rules/jep-adr-process.md | 77 +-------------- .claude/skills/create-adr/SKILL.md | 94 +------------------ .claude/skills/propose-jep/SKILL.md | 61 +----------- .cursor/skills/create-adr/SKILL.md | 2 +- .cursor/skills/propose-jep/SKILL.md | 2 +- python/docs/source/index.md | 2 +- python/docs/source/internal/adr/index.md | 4 + .../internal/jeps/JEP-0000-jep-process.md | 1 + .../jeps/JEP-0010-renode-integration.md | 2 +- .../source/internal/jeps/JEP-NNNN-template.md | 15 +++ python/docs/source/internal/jeps/README.md | 56 +++-------- 11 files changed, 39 insertions(+), 277 deletions(-) mode change 100644 => 120000 .claude/rules/jep-adr-process.md mode change 100644 => 120000 .claude/skills/create-adr/SKILL.md mode change 100644 => 120000 .claude/skills/propose-jep/SKILL.md diff --git a/.claude/rules/jep-adr-process.md b/.claude/rules/jep-adr-process.md deleted file mode 100644 index 60439838d..000000000 --- a/.claude/rules/jep-adr-process.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -alwaysApply: false ---- - -# JEP and ADR Process - -This rule helps with creating Jumpstarter Enhancement Proposals (JEPs) and Architecture Decision Records (ADRs). - -## When to Use - -- **JEP**: Cross-cutting changes that affect multiple components, change public APIs or protocols, or require community consensus. -- **ADR**: Scoped technical decisions within a single component or driver that should be documented for posterity. - -## 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 `Proposed` 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. - -## Creating an ADR - -1. Create the ADR file in `python/docs/source/internal/adr/` following the existing ADR format in that directory. - -2. ADRs are submitted alongside the implementation PR, not as separate PRs. - -3. Each ADR should document: - - Context: Why the decision was needed - - Decision: What was decided - - Alternatives considered - - Consequences (positive and negative) - -## Design Decision Format (DD-N) - -Both JEPs and ADRs 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/` -- ADRs live in `python/docs/source/internal/adr/` -- 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 diff --git a/.claude/rules/jep-adr-process.md b/.claude/rules/jep-adr-process.md new file mode 120000 index 000000000..c3997885b --- /dev/null +++ b/.claude/rules/jep-adr-process.md @@ -0,0 +1 @@ +../../.cursor/rules/jep-adr-process.mdc \ No newline at end of file diff --git a/.claude/skills/create-adr/SKILL.md b/.claude/skills/create-adr/SKILL.md deleted file mode 100644 index 145259454..000000000 --- a/.claude/skills/create-adr/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: create-adr -description: Create a new Architecture Decision Record (ADR) -argument-hint: Short title or description of the decision ---- - -# Create an ADR - -You are helping the user create a new Architecture Decision Record (ADR). - -## Context - -ADRs document significant technical decisions scoped to a single component or driver. Unlike JEPs, ADRs are submitted alongside the implementation PR, not as separate proposals. Read `.claude/rules/jep-adr-process.md` for the full process definition. - -ADR topic: $ARGUMENTS - -## Steps - -### 1. Determine the next ADR number - -List existing files in `python/docs/source/internal/adr/` and pick the next available incrementing integer. Use the format `ADR-NNNN-short-title.md`. - -### 2. Gather information - -Ask the user about: - -- **Context**: What situation or problem prompted this decision? What component or driver is this for? -- **Decision**: What was decided? -- **Alternatives**: What other options were considered? Why were they rejected? -- **Consequences**: What are the positive and negative outcomes of this decision? - -If the user provided a description in `$ARGUMENTS`, use it as a starting point but still ask about gaps. - -### 3. Create the ADR file - -Create a new file at `python/docs/source/internal/adr/ADR-NNNN-short-title.md` with the following structure: - -```markdown -# ADR-NNNN: Title - -| Field | Value | -|----------------|--------------------------------| -| **ADR** | NNNN | -| **Title** | Short descriptive title | -| **Author(s)** | Name | -| **Status** | Accepted | -| **Created** | YYYY-MM-DD | -| **Component** | Component or driver name | - -## Context - -[Why this decision was needed] - -## Design Decisions - -### DD-1: Decision title - -**Alternatives considered:** - -1. **Option A** -- Description. -2. **Option B** -- Description. - -**Decision:** Chosen option. - -**Rationale:** Why this option was chosen. - -## Consequences - -### Positive - -- [List positive outcomes] - -### Negative - -- [List negative outcomes or trade-offs] -``` - -Use the DD-N format for each design decision, consistent with the JEP convention. - -### 4. Update the ADR index - -Update `python/docs/source/internal/adr/index.md`: - -- Remove the "*No ADRs have been submitted yet.*" placeholder if present -- Add a table listing the new ADR -- Add a `{toctree}` directive if one doesn't exist yet, including the new ADR file - -### 5. Present the result - -Show the user: - -- The file path of the new ADR -- A reminder that ADRs are submitted alongside the implementation PR, not separately diff --git a/.claude/skills/create-adr/SKILL.md b/.claude/skills/create-adr/SKILL.md new file mode 120000 index 000000000..0387e6119 --- /dev/null +++ b/.claude/skills/create-adr/SKILL.md @@ -0,0 +1 @@ +../../../.cursor/skills/create-adr/SKILL.md \ No newline at end of file diff --git a/.claude/skills/propose-jep/SKILL.md b/.claude/skills/propose-jep/SKILL.md deleted file mode 100644 index fde739f18..000000000 --- a/.claude/skills/propose-jep/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -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 `.claude/rules/jep-adr-process.md` 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 `Proposed` when the PR is ready for review -- Remind them to apply the `jep` label to their pull request diff --git a/.claude/skills/propose-jep/SKILL.md b/.claude/skills/propose-jep/SKILL.md new file mode 120000 index 000000000..822ae5787 --- /dev/null +++ b/.claude/skills/propose-jep/SKILL.md @@ -0,0 +1 @@ +../../../.cursor/skills/propose-jep/SKILL.md \ No newline at end of file diff --git a/.cursor/skills/create-adr/SKILL.md b/.cursor/skills/create-adr/SKILL.md index 145259454..8e0c6e7cf 100644 --- a/.cursor/skills/create-adr/SKILL.md +++ b/.cursor/skills/create-adr/SKILL.md @@ -10,7 +10,7 @@ You are helping the user create a new Architecture Decision Record (ADR). ## Context -ADRs document significant technical decisions scoped to a single component or driver. Unlike JEPs, ADRs are submitted alongside the implementation PR, not as separate proposals. Read `.claude/rules/jep-adr-process.md` for the full process definition. +ADRs document significant technical decisions scoped to a single component or driver. Unlike JEPs, ADRs are submitted alongside the implementation PR, not as separate proposals. Read `.cursor/rules/jep-adr-process.mdc` for the full process definition. ADR topic: $ARGUMENTS diff --git a/.cursor/skills/propose-jep/SKILL.md b/.cursor/skills/propose-jep/SKILL.md index fde739f18..68c61ce8a 100644 --- a/.cursor/skills/propose-jep/SKILL.md +++ b/.cursor/skills/propose-jep/SKILL.md @@ -10,7 +10,7 @@ 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 `.claude/rules/jep-adr-process.md` for the full process definition. +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 diff --git a/python/docs/source/index.md b/python/docs/source/index.md index 0319f8366..97d831dbb 100644 --- a/python/docs/source/index.md +++ b/python/docs/source/index.md @@ -60,4 +60,4 @@ glossary.md reference/index.md internal/index.md -``` \ No newline at end of file +``` diff --git a/python/docs/source/internal/adr/index.md b/python/docs/source/internal/adr/index.md index f73afc188..b0bf7a95d 100644 --- a/python/docs/source/internal/adr/index.md +++ b/python/docs/source/internal/adr/index.md @@ -8,3 +8,7 @@ For guidance on when to use an ADR vs a JEP, see [JEP-0000](../jeps/JEP-0000-jep-process.md). *No ADRs have been submitted yet.* + +```{toctree} +:hidden: +``` diff --git a/python/docs/source/internal/jeps/JEP-0000-jep-process.md b/python/docs/source/internal/jeps/JEP-0000-jep-process.md index 490e1bd9f..2356ad215 100644 --- a/python/docs/source/internal/jeps/JEP-0000-jep-process.md +++ b/python/docs/source/internal/jeps/JEP-0000-jep-process.md @@ -133,6 +133,7 @@ flowchart TD | **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 diff --git a/python/docs/source/internal/jeps/JEP-0010-renode-integration.md b/python/docs/source/internal/jeps/JEP-0010-renode-integration.md index 859d4fbbf..0a815784c 100644 --- a/python/docs/source/internal/jeps/JEP-0010-renode-integration.md +++ b/python/docs/source/internal/jeps/JEP-0010-renode-integration.md @@ -357,7 +357,7 @@ SoCs while Renode fills the MCU gap. ## Implementation History -- 2026-04-06 JEP proposed +- 2026-04-06: JEP proposed - 2026-04-06: Initial implementation proposed ([PR #533](https://github.com/jumpstarter-dev/jumpstarter/pull/533)) - 2026-04-11: Address review feedback (DEVNULL, try-except cleanup, diff --git a/python/docs/source/internal/jeps/JEP-NNNN-template.md b/python/docs/source/internal/jeps/JEP-NNNN-template.md index 86c386fc2..0c6b4130d 100644 --- a/python/docs/source/internal/jeps/JEP-NNNN-template.md +++ b/python/docs/source/internal/jeps/JEP-NNNN-template.md @@ -177,6 +177,21 @@ Reference specific project constraints, prior art, or technical tradeoffs. the implementation? --> +## Acceptance Criteria *(mandatory for Standards Track)* + + + ## Graduation Criteria *(optional)* B[Draft] - B -->|PR opened| C[Proposed] + B -->|PR opened| C[Discussion] C -->|Maintainers approve| D[Accepted] C -->|Maintainers decline| E[Rejected] D -->|Work begins| F[Implementing] @@ -125,7 +102,7 @@ flowchart TD | Status | Meaning | | ---------------- | ------------------------------------------------------------------------------------ | | **Draft** | Author is still writing the JEP. Not yet open for formal review. | -| **Proposed** | JEP PR is open and under community discussion. | +| **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. | @@ -173,7 +150,7 @@ 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 **Proposed** when the PR is ready for review. +the JEP status to **Discussion** when the PR is ready for review. ### 3. Discussion and Revision diff --git a/python/docs/source/internal/jeps/JEP-NNNN-template.md b/python/docs/source/internal/jeps/JEP-NNNN-template.md index 0c6b4130d..f3b9b5a93 100644 --- a/python/docs/source/internal/jeps/JEP-NNNN-template.md +++ b/python/docs/source/internal/jeps/JEP-NNNN-template.md @@ -15,8 +15,7 @@ orphan: true - Hardware-related proposals must address the Hardware Considerations section. - Protocol/API changes must include backward compatibility analysis. - Write as if teaching the feature to a new Jumpstarter contributor. - - Each design decision should document alternatives considered and rationale - (following the ADR pattern used in the project). + - Each design decision should document alternatives considered and rationale. - Sections marked (mandatory) must be filled in. Sections marked (optional) may be omitted if not applicable. --> @@ -114,8 +113,6 @@ orphan: true ### Positive diff --git a/python/docs/source/internal/jeps/README.md b/python/docs/source/internal/jeps/README.md index 526d62863..b5e02e780 100644 --- a/python/docs/source/internal/jeps/README.md +++ b/python/docs/source/internal/jeps/README.md @@ -42,14 +42,6 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md). | ---------- | ----- | ------ | --------- | | *none yet* | | | | -## Related: Architecture Decision Records (ADRs) - -For technical decisions scoped to a single component or driver (e.g., choosing a -control interface for a new driver), use an Architecture Decision Record instead -of a JEP. ADRs live in `python/docs/source/internal/adr/` and are submitted -alongside the implementation PR. See [JEP-0000](JEP-0000-jep-process.md) for -guidance on when to use a JEP vs an ADR. - ## Status Key > **Note:** [JEP-0000](JEP-0000-jep-process.md) is the canonical source for @@ -58,7 +50,7 @@ guidance on when to use a JEP vs an ADR. | Status | Meaning | | ------------ | ------------------------------------------------ | | Draft | Author is still writing; not yet open for review | -| Proposed | PR is open and under community discussion | +| Discussion | PR is open and under community discussion | | Accepted | Design approved; implementation may begin | | Implementing | Implementation in progress | | Implemented | Reference implementation merged | @@ -71,7 +63,7 @@ guidance on when to use a JEP vs an ADR. ## For AI Agents -For detailed conventions on creating JEPs and ADRs, see the agent rule files +For detailed conventions on creating JEPs, see the agent rule files in `.cursor/rules/jep-adr-process.mdc` (or `.claude/rules/jep-adr-process.md`). Key references: From f7b01d08dcebcc4463a4d7d267d87630c6563ada Mon Sep 17 00:00:00 2001 From: Miguel Angel Ajo Pelayo Date: Thu, 23 Apr 2026 10:24:49 +0200 Subject: [PATCH 11/13] chore: rename jep-adr-process rule to jep-process - Rename .cursor/rules/jep-adr-process.mdc to jep-process.mdc - Replace .claude symlink with jep-process.md -> ../../.cursor/rules/jep-process.mdc - Update propose-jep skill and JEPs README references Made-with: Cursor --- .claude/rules/jep-adr-process.md | 1 - .claude/rules/jep-process.md | 1 + .cursor/rules/{jep-adr-process.mdc => jep-process.mdc} | 0 .cursor/skills/propose-jep/SKILL.md | 2 +- python/docs/source/internal/jeps/README.md | 2 +- 5 files changed, 3 insertions(+), 3 deletions(-) delete mode 120000 .claude/rules/jep-adr-process.md create mode 120000 .claude/rules/jep-process.md rename .cursor/rules/{jep-adr-process.mdc => jep-process.mdc} (100%) diff --git a/.claude/rules/jep-adr-process.md b/.claude/rules/jep-adr-process.md deleted file mode 120000 index c3997885b..000000000 --- a/.claude/rules/jep-adr-process.md +++ /dev/null @@ -1 +0,0 @@ -../../.cursor/rules/jep-adr-process.mdc \ No newline at end of file diff --git a/.claude/rules/jep-process.md b/.claude/rules/jep-process.md new file mode 120000 index 000000000..1fc31d7b0 --- /dev/null +++ b/.claude/rules/jep-process.md @@ -0,0 +1 @@ +../../.cursor/rules/jep-process.mdc \ No newline at end of file diff --git a/.cursor/rules/jep-adr-process.mdc b/.cursor/rules/jep-process.mdc similarity index 100% rename from .cursor/rules/jep-adr-process.mdc rename to .cursor/rules/jep-process.mdc diff --git a/.cursor/skills/propose-jep/SKILL.md b/.cursor/skills/propose-jep/SKILL.md index 376749a8a..ea177b20f 100644 --- a/.cursor/skills/propose-jep/SKILL.md +++ b/.cursor/skills/propose-jep/SKILL.md @@ -10,7 +10,7 @@ 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. +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-process.mdc` for the full process definition. JEP topic: $ARGUMENTS diff --git a/python/docs/source/internal/jeps/README.md b/python/docs/source/internal/jeps/README.md index b5e02e780..236c296a1 100644 --- a/python/docs/source/internal/jeps/README.md +++ b/python/docs/source/internal/jeps/README.md @@ -64,7 +64,7 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md). ## For AI Agents For detailed conventions on creating JEPs, see the agent rule files -in `.cursor/rules/jep-adr-process.mdc` (or `.claude/rules/jep-adr-process.md`). +in `.cursor/rules/jep-process.mdc` (or `.claude/rules/jep-process.md`). Key references: From e9063f279d51b91b292296d9fc97f18dfaeb3fdd Mon Sep 17 00:00:00 2001 From: Miguel Angel Ajo Pelayo Date: Thu, 23 Apr 2026 10:47:27 +0200 Subject: [PATCH 12/13] docs: mention JEP process in CLAUDE.md - Link .claude/rules/jep-process.md in the project rules list - Add 'When creating JEPs' to the when-to-read section Made-with: Cursor --- CLAUDE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ade44965e..d3b1e32d2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,11 +12,14 @@ Important project-specific rules and guidelines are located in the `.claude/rule - **`.claude/rules/releasing-operator.md`**: Step-by-step guide for releasing a new version of the Jumpstarter operator, including which files to update, image tag conventions, bundle generation, and community-operators contribution workflow. +- **`.claude/rules/jep-process.md`**: Process for creating Jumpstarter Enhancement Proposals (JEPs), including when to use them, numbering conventions, required sections, and the design decision format. Read this when proposing or reviewing cross-cutting changes or features that require community consensus. + ## When to Read These Rules - **Always**: Read `project-structure.md` when working with files, packages, or understanding the codebase layout - **When creating drivers**: Read `creating-new-drivers.md` before creating, improving, or documenting driver packages - **When releasing the operator**: Read `releasing-operator.md` before preparing a new operator version for OLM +- **When creating JEPs**: Read `jep-process.md` before proposing enhancements that affect multiple components, change public APIs, or require community discussion - **When modifying structure**: Consult both files when making changes that affect project organization ## Key Information From bc53d462de0ffc473b94f458a68bf1df6be0497d Mon Sep 17 00:00:00 2001 From: Miguel Angel Ajo Pelayo Date: Thu, 23 Apr 2026 10:51:24 +0200 Subject: [PATCH 13/13] docs(jeps): drop redundant For AI Agents section from README Agent-oriented JEP conventions remain in .cursor/rules/jep-process.mdc; the index stays human-focused. Made-with: Cursor --- python/docs/source/internal/jeps/README.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/python/docs/source/internal/jeps/README.md b/python/docs/source/internal/jeps/README.md index 236c296a1..bba33ef35 100644 --- a/python/docs/source/internal/jeps/README.md +++ b/python/docs/source/internal/jeps/README.md @@ -61,18 +61,6 @@ For the full process definition, see [JEP-0000](JEP-0000-jep-process.md). | Active | Living document, actively maintained (Process JEPs only) | | Superseded | Replaced by a newer JEP | -## For AI Agents - -For detailed conventions on creating JEPs, see the agent rule files -in `.cursor/rules/jep-process.mdc` (or `.claude/rules/jep-process.md`). - -Key references: - -- **Template**: `JEP-NNNN-template.md` in this directory -- **Canonical process definition**: [JEP-0000](JEP-0000-jep-process.md) -- **File naming**: `JEP-NNNN-short-title.md` (zero-padded 4-digit number) -- **JEP numbering**: Incrementing integers, not derived from PR numbers. - JEP-0000 through JEP-0009 are reserved for process/meta-JEPs. ```{toctree} :hidden: