Add Jumpstarter Enhancement Proposal (JEP) Process and Issue Template#423
Add Jumpstarter Enhancement Proposal (JEP) Process and Issue Template#423kirkbrauer wants to merge 8 commits intomainfrom
Conversation
❌ Deploy Preview for jumpstarter-docs failed. Why did it fail? →
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a Jumpstarter Enhancement Proposal (JEP) governance system: a process specification, a reusable JEP template, a README index, and corresponding rule files describing when to use JEPs vs ADRs, numbering, metadata, and submission workflow. All changes are documentation-only. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
jep/JEP-0000-jep-process.md (1)
140-142: Add language specifier to fenced code block.The fenced code block is missing a language specifier, which is flagged by markdownlint.
📝 Proposed fix
-``` +```text JEP: Short descriptive title</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@jep/JEP-0000-jep-process.mdaround lines 140 - 142, The fenced code block
containing "JEP: Short descriptive title" lacks a language specifier (triggering
markdownlint); update that fenced block (the triple-backtick block that wraps
the line "JEP: Short descriptive title") to include a language tag such as text
(e.g., ```text) so the block is properly annotated.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.github/ISSUE_TEMPLATE/jep-proposal.yml:
- Line 12: Update the broken Markdown link string
"https://github.com/jumpstarter-dev/jumpstarter/blob/main/jeps/JEP-0000-jep-process.md"
to use the correct directory name by replacing "jeps/" with "jep/" so the link
points to
"https://github.com/jumpstarter-dev/jumpstarter/blob/main/jep/JEP-0000-jep-process.md";
locate the URL in the ISSUE_TEMPLATE jep-proposal YAML entry (the line
containing the JEP-0000 reference) and update the path accordingly.In
@jep/JEP-0000-jep-process.md:
- Line 203: Update the incorrect directory path reference in the JEP text:
replace the occurrence of "jeps/README.md" with the correct "jep/README.md" in
the document (JEP-0000-jep-process.md) so it points to the actual README in the
jep/ directory.
Nitpick comments:
In@jep/JEP-0000-jep-process.md:
- Around line 140-142: The fenced code block containing "JEP: Short descriptive
title" lacks a language specifier (triggering markdownlint); update that fenced
block (the triple-backtick block that wraps the line "JEP: Short descriptive
title") to include a language tag such as text (e.g., ```text) so the block is
properly annotated.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `5aed2daa-10d5-4d72-a927-5a6ff2159142` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between d713354eeaea42fe7774665a561a07da404e5598 and 652b3d2a7b591889b699aafd65bbc33fbe214c66. </details> <details> <summary>📒 Files selected for processing (4)</summary> * `.github/ISSUE_TEMPLATE/jep-proposal.yml` * `jep/JEP-0000-jep-process.md` * `jep/JEP-NNNN-template.md` * `jep/README.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
|
This is a great idea, having a structured process for substantial changes brings much-needed formality and a clear planning trail, especially for anything touching interfaces, the gRPC protocol, or CRDs where mistakes are expensive to undo, etc. One optional idea for down the road: once a JEP is approved, we could experiment with spec-kit deriving a spec-kit spec from a JEP. :) |
|
@ambient-code Let's go ahead and remove the issue template and standardize the process on creating PRs for formal proposals. |
|
Done. I've removed the |
|
@ambient-code Let's go ahead and make this align with the SpecKit (https://github.com/github/spec-kit) standards for specifications that can be implemented by agents. We might also want to pull in Architecture Decision Records (ADRs) similar to the one added into this PR: #533 |
|
I've reviewed both SpecKit and the ADR format from PR #533 and made the following changes to align the JEP process: JEP template (
Process document (
Index (
What I intentionally did not adopt from SpecKit: SpecKit's full workflow ( |
kirkbrauer
left a comment
kirkbrauer
left a comment
There was a problem hiding this comment.
@ambient-code Let's address these comments first before further reviews.
Restructure the Renode integration ADR to follow the JEP template format: metadata table, Abstract, Motivation, Rejected Alternatives, Prior Art, Implementation History, and References sections. The DD-N design decisions and Consequences sections were already aligned. Made-with: Cursor
|
@ambient-code Finally, we should migrate the ADRs and JEPs into the docs directory for consistency so we can render it as part of the documentation. |
|
Migrated JEPs and ADRs into the docs directory for documentation rendering:
The physical file locations now match the paths already documented in JEP-0000, the rules files, and the JEP template. This enables rendering JEPs and ADRs as part of the project documentation site. |
Move the Renode integration design document from python/docs/source/contributing/adr/ to the JEP directory at docs/internal/jeps/, following the JEP template from PR jumpstarter-dev#423. Adds mandatory sections (Proposal, Design Details, Test Plan, Backward Compatibility, User Stories, Future Possibilities) and a new DD-5 for security decisions (allow_raw_monitor, load_command allowlist, newline rejection). Made-with: Cursor
Restructure the Renode integration ADR to follow the JEP template format: metadata table, Abstract, Motivation, Rejected Alternatives, Prior Art, Implementation History, and References sections. The DD-N design decisions and Consequences sections were already aligned. Made-with: Cursor
Move the Renode integration design document from python/docs/source/contributing/adr/ to the JEP directory at docs/internal/jeps/, following the JEP template from PR jumpstarter-dev#423. Adds mandatory sections (Proposal, Design Details, Test Plan, Backward Compatibility, User Stories, Future Possibilities) and a new DD-5 for security decisions (allow_raw_monitor, load_command allowlist, newline rejection). Made-with: Cursor
- 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
- Add structured Design Decisions (DD-N) section to JEP template following the ADR pattern used in the project (e.g., ADR-0001 from PR #533) - Add Consequences section (positive/negative/risks) to JEP template - Mark all template sections as mandatory, optional, or conditional - Document the relationship between JEPs and ADRs in JEP-0000 - Add SpecKit and ADR references to Prior Art in JEP-0000 - Add agent instructions and document conventions to jeps/README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Unify documentation location to docs/internal/ for JEPs and ADRs - Clarify JEP numbers are incrementing integers, not PR numbers - Clarify JEPs should always be merged as PRs into docs/source - Update rejection policy: rejected JEPs not merged unless architectural reason - Add claude/cursor rules to assist with JEP/ADR generation workflow Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Move JEP files from jeps/ to docs/internal/jeps/ and create docs/internal/adr/ directory, matching the paths already referenced in the documentation. Update all internal references in the JEP process document, README, and claude/cursor rules files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
| @@ -0,0 +1,76 @@ | |||
| --- | |||
There was a problem hiding this comment.
[HIGH] The existing .claude/rules/ directory uses symlinks that point to .cursor/rules/ as the single source of truth (e.g. creating-new-drivers.md -> ../../.cursor/rules/creating-new-drivers.mdc). All three new .claude/ files in this PR are regular files with content duplicated verbatim across both directories. If someone edits one copy later, the other will silently diverge.
Suggestion: follow the existing convention and make .cursor/ the source of truth, then replace these .claude/ copies with symlinks (e.g. .claude/rules/jep-adr-process.md -> ../../.cursor/rules/jep-adr-process.mdc). Same for the skill directories.
AI-generated, human reviewed
| @@ -0,0 +1,298 @@ | |||
| --- | |||
There was a problem hiding this comment.
[MEDIUM] The template is missing an "Acceptance Criteria" section. It has motivation, design decisions, consequences, and rejected alternatives, but no place for authors to define measurable criteria for when a proposal's goals have been met. The closest section is "Graduation Criteria" which is optional and serves a different purpose.
Suggestion: add an ## Acceptance Criteria section (mandatory for Standards Track JEPs) with guidance on defining measurable success criteria.
AI-generated, human reviewed
| | 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. | |
There was a problem hiding this comment.
[MEDIUM] The lifecycle states use "Proposed" instead of "Discussion" as defined earlier in the spec. The additional states (Implementing, Final, Deferred) are fine as additive, but renaming "Discussion" to "Proposed" is a semantic change that creates a mismatch.
Suggestion: either rename the "Proposed" state back to "Discussion" here, or update the spec to reflect the chosen name.
AI-generated, human reviewed
| | **JEP** | 0000 | | ||
| | **Title** | Jumpstarter Enhancement Proposal Process | | ||
| | **Author(s)** | Jumpstarter Maintainers | | ||
| | **Status** | Active | |
There was a problem hiding this comment.
[MEDIUM] The metadata table sets Status: Active, but "Active" is not one of the 10 lifecycle states defined later in this same document (lines 125-136), nor in the README status key. JEP-0000 defines the valid statuses for all JEPs but then uses an undefined status for itself.
Suggestion: add "Active" to the lifecycle states table and README status key with a definition like "Living document, actively maintained and updated as the process evolves" (similar to how Python's PEP-0001 uses "Active" for process PEPs).
AI-generated, human reviewed
|
|
||
| ## 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. |
There was a problem hiding this comment.
[MEDIUM] This Cursor skill file references .claude/rules/jep-adr-process.md but it should reference the Cursor-specific equivalent .cursor/rules/jep-adr-process.mdc. A Cursor agent following this instruction would be directed to read a Claude-specific config file rather than its own.
Same issue exists in .cursor/skills/create-adr/SKILL.md:13.
AI-generated, human reviewed
| 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.* |
There was a problem hiding this comment.
[MEDIUM] The JEP index (README.md) correctly includes a {toctree} directive listing all JEP files for Sphinx navigation, but this ADR index page has no toctree. When ADRs are eventually created, they won't appear in the rendered docs navigation unless someone manually adds a toctree later.
Suggestion: add an empty toctree directive here and update the create-adr skill to mention adding new ADR files to it.
AI-generated, human reviewed
| ## 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 | ||
| `python/docs/source/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. |
There was a problem hiding this comment.
[MEDIUM] The "For AI Agents" section adds machine-oriented parsing conventions (metadata table format, section marker semantics, DD-N format, file naming regex, numbering rules) into what is otherwise a human-readable index. This same information already exists in the dedicated agent rule files (.claude/rules/jep-adr-process.md, .cursor/rules/jep-adr-process.mdc), so it is duplicated.
Suggestion: move the "For AI Agents" content into the agent rule files, which are purpose-built for machine consumers.
AI-generated, human reviewed
|
|
||
| reference/index.md | ||
| internal/index.md | ||
| ``` No newline at end of file |
There was a problem hiding this comment.
[LOW] The file is missing a trailing newline. The diff shows No newline at end of file. Since this PR already modified the file (adding internal/index.md to the toctree), it would be a nice cleanup to add the missing trailing newline for POSIX compliance.
AI-generated, human reviewed
|
|
||
| | 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 | |
There was a problem hiding this comment.
[LOW] The lifecycle status table, DD-N format, and JEP numbering rules are substantively repeated in JEP-0000 (authoritative), README (quick reference), and the agent rules files, but none of the secondary copies indicate that JEP-0000 is the canonical source. If the process evolves, multiple files will need synchronized updates.
Suggestion: add a brief note to the README status table and agent rules indicating that JEP-0000 is the canonical source.
AI-generated, human reviewed
| | **Discussion** | [PR #533](https://github.com/jumpstarter-dev/jumpstarter/pull/533) | | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
[LOW] Minor: in the Implementation History section (not shown in the diff, but visible in the full file), line 360 uses - 2026-04-06 JEP proposed (no colon) while line 361 uses - 2026-04-06: Initial implementation proposed (with colon). The template's documented format uses colons (- YYYY-MM-DD: description). Consider adding a colon after the date on line 360 for consistency.
AI-generated, human reviewed
3 participants
No description provided.