diff --git a/.claude/rules/jep-adr-process.md b/.claude/rules/jep-adr-process.md new file mode 100644 index 000000000..df97fcf71 --- /dev/null +++ b/.claude/rules/jep-adr-process.md @@ -0,0 +1,76 @@ +--- +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 `docs/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 `docs/internal/jeps/JEP-NNNN-template.md` to `docs/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 `docs/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 `docs/internal/jeps/` +- ADRs live in `docs/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/.cursor/rules/jep-adr-process.mdc b/.cursor/rules/jep-adr-process.mdc new file mode 100644 index 000000000..df97fcf71 --- /dev/null +++ b/.cursor/rules/jep-adr-process.mdc @@ -0,0 +1,76 @@ +--- +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 `docs/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 `docs/internal/jeps/JEP-NNNN-template.md` to `docs/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 `docs/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 `docs/internal/jeps/` +- ADRs live in `docs/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/docs/internal/adr/.gitkeep b/docs/internal/adr/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/internal/jeps/JEP-0000-jep-process.md b/docs/internal/jeps/JEP-0000-jep-process.md new file mode 100644 index 000000000..9712a7467 --- /dev/null +++ b/docs/internal/jeps/JEP-0000-jep-process.md @@ -0,0 +1,256 @@ +# 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. + +## JEPs and Architecture Decision Records (ADRs) + +The project uses both JEPs and Architecture Decision Records (ADRs). They serve +different purposes and operate at different scopes: + +| Aspect | JEP | ADR | +|---------------|--------------------------------------------|----------------------------------------------------| +| **Scope** | Cross-cutting changes to the project | Scoped to a single component or driver | +| **Process** | Requires community review and maintainer approval | Included with the implementation PR | +| **When** | Before implementation begins | Alongside or within an implementation PR | +| **Location** | `docs/internal/jeps/` directory | `docs/internal/adr/` directory | +| **Example** | New lease scheduling strategy | Choice of telnet vs pyrenode3 for Renode driver | + +**Use a JEP** when the change affects multiple components, changes public APIs or +protocols, or requires community consensus. **Use an ADR** when you are making a +significant technical decision within a self-contained piece of work (e.g., a new +driver) that does not need project-wide review but should be documented for +posterity. + +JEPs borrow the structured decision format from ADRs: each design decision in a +JEP should document alternatives considered and rationale, following the `DD-N` +pattern in the [JEP template](JEP-NNNN-template.md). + +## 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. Submit a JEP Pull Request + +Create a new branch and add your JEP as a markdown file in the `docs/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 +`docs/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 **Proposed** 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 `docs/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. diff --git a/docs/internal/jeps/JEP-NNNN-template.md b/docs/internal/jeps/JEP-NNNN-template.md new file mode 100644 index 000000000..70e2e6bf9 --- /dev/null +++ b/docs/internal/jeps/JEP-NNNN-template.md @@ -0,0 +1,294 @@ +# 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)* | + +--- + +## Abstract *(mandatory)* + + + +## Motivation *(mandatory)* + + + +### User Stories *(optional)* + + + +## Proposal *(mandatory)* + + + +### API / Protocol Changes *(if applicable)* + + + +### Hardware Considerations *(if applicable)* + + + +## 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 *(mandatory for Standards Track)* + + + +## Graduation Criteria *(optional)* + + + +## Backward Compatibility *(mandatory for Standards Track)* + + + +## Consequences *(mandatory)* + + + +### Positive + + + +### Negative + + + +### Risks *(optional)* + + + +## Rejected Alternatives *(mandatory)* + + + +## Prior Art *(optional)* + + + +## Unresolved Questions *(optional)* + + + +## 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/docs/internal/jeps/README.md b/docs/internal/jeps/README.md new file mode 100644 index 000000000..7bad684e4 --- /dev/null +++ b/docs/internal/jeps/README.md @@ -0,0 +1,115 @@ +# 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. Create a branch and add your JEP markdown file to the `docs/internal/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. + +## 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* | | | | + +## 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 `docs/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 + +| 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 + +This section provides conventions for AI agents working with JEPs. + +### Document structure + +JEP files are Markdown documents with a metadata table at the top. The metadata +table uses pipe-delimited rows with bold field names. Required fields: +`JEP`, `Title`, `Author(s)`, `Status`, `Type`, `Created`. + +### Section markers + +Sections in the JEP template are marked `*(mandatory)*`, `*(optional)*`, or +`*(mandatory for Standards Track)*`. When helping an author draft a JEP, ensure +all mandatory sections are filled in. Optional sections may be omitted entirely. + +### Design Decisions format + +Each design decision uses a numbered `DD-N` subsection under `## Design Decisions` +with the following structure: + +```text +### DD-N: Decision title + +**Alternatives considered:** + +1. **Option A** — Description. +2. **Option B** — Description. + +**Decision:** Chosen option. + +**Rationale:** Why this option was chosen. +``` + +This matches the ADR convention used elsewhere in the project (see +`docs/internal/adr/`). + +### File naming + +JEP files are named `JEP-NNNN-short-title.md` where `NNNN` is the next +available incrementing integer (zero-padded to 4 digits). The template file +is `JEP-NNNN-template.md`. + +### JEP numbering + +The JEP number is an incrementing integer assigned sequentially; it is not +derived from the pull request number. JEP-0000 through JEP-0009 are +reserved for process and meta-JEPs.