Add Jumpstarter Enhancement Proposal (JEP) Process and Issue Template#423
Add Jumpstarter Enhancement Proposal (JEP) Process and Issue Template#423kirkbrauer wants to merge 5 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:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
✅ Files skipped from review due to trivial changes (5)
📝 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. :) |
jep/README.md
Outdated
| 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. |
There was a problem hiding this comment.
I think it would be better to materialize JEPs as PRs always. It makes discussion easier. But that is probably something we can automate and convert issues into PRs at will. But it would be good to explain it here.
There was a problem hiding this comment.
Updated both the README and JEP-0000 process doc to clarify that JEPs should be submitted as pull requests containing the JEP markdown file. The PR-based workflow is now presented as the primary path, with issues available for initial discussion or lightweight proposals.
- 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>
| 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. | ||
|
|
There was a problem hiding this comment.
ok, I wanted to discuss about this but ambient code went ahead ... lol...
WDYT @kirkbrauer ?
There was a problem hiding this comment.
Yeah, so we could use PRs or Issues to track these (or maybe both), that's why I added the issue template.
|
@ambient-code Let's go ahead and remove the issue template and standardize the process on creating PRs for formal proposals. |
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>
|
Done. I've removed the |
jeps/JEP-0000-jep-process.md
Outdated
|
|
||
| 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). |
There was a problem hiding this comment.
I think that using the PR number is not very deterministic, we should probably do sequential PRs. i.e. at the time of creating a new PR you can try to guess which number is next (counter is shared across issues and PRs, not sure if something else.)
I think it's just simpler to use a monotonic JEP counter, and manually fix when two competing PRs collide on the JEP number.
WDYT?
There was a problem hiding this comment.
@ambient-code Let's clartify that the JEP number is just an incrementing integer, not reflective of the PR#.
There was a problem hiding this comment.
Clarified that JEP numbers are incrementing integers assigned sequentially, not derived from PR numbers. Updated the workflow section, the numbering section, the template metadata, and the README's agent-facing documentation to all reflect this.
| 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 |
There was a problem hiding this comment.
@kirkbrauer we must decide if we merge the PRs with rejected JEPs, or not.
We have two options:
- Not merge them, but github will keep the history on the PR, including comments, rationale, etc.
- Merge them, clearly marked as rejected, may be using a sub-directory?
I would say that 2 gives us future context for any later decision making.
WDYT?
There was a problem hiding this comment.
@ambient-code We should always merge the JEPs as PRs so the Markdown documentation is incorporated directly into the Jumpstarter docs/source.
There was a problem hiding this comment.
Added clarification in the Decision section that JEPs should always be merged as PRs so the markdown documentation is incorporated directly into the Jumpstarter docs/source.
jeps/JEP-0000-jep-process.md
Outdated
| 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 |
There was a problem hiding this comment.
if we want to merge the rejections, it's probably something we can automate with the bot, 1) move to a jeps/rejected directory 2) add a clear rejected message, collecting the reasoning in the PR discussions, etc..
There was a problem hiding this comment.
@ambient-code Let's clarify that the rejected JEPs will not be accepted as PRs, but if there is an architectural reason to merge them, then we can merge them with a "Rejected" status.
There was a problem hiding this comment.
Updated the rejection section: rejected JEPs are normally not merged as PRs. However, if there is an architectural reason to preserve them (e.g., documenting why an approach was not taken), they may be merged with a "Rejected" status clearly set in the metadata.
jeps/JEP-0000-jep-process.md
Outdated
| ## 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. |
There was a problem hiding this comment.
We need to decide on this. May be one option is simply submit a bogus/expected one, then self-correct? IDK
jeps/JEP-NNNN-template.md
Outdated
| document is preferred (e.g., attaching to an issue or linking from one). | ||
| Use this template to create your JEP. Copy it to a new file named | ||
| JEP-NNNN-short-title.md (where NNNN will be the PR number) and open a | ||
| pull request against the main branch. |
There was a problem hiding this comment.
Should we add some .cursor/rules .claude/rules to help with this process? i.e. ask a few questions to the user, and prepare the initial template, even try to figure out what is the next PR number :)
There was a problem hiding this comment.
@ambient-code Let's add some claude/cursor rules to help out with this process of generating JEPs/ADRs and filling out the initial template, choosing the number, etc.
There was a problem hiding this comment.
Added claude and cursor rules files (.claude/rules/jep-adr-process.md and .cursor/rules/jep-adr-process.mdc) that guide agents through the JEP/ADR creation process, including how to choose the next number, which template to use, what sections are mandatory, and the design decision DD-N format.
|
@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 |
- 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>
|
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.
jeps/JEP-0000-jep-process.md
Outdated
| | **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** | `jeps/` directory | `python/docs/source/contributing/adr/` directory | |
There was a problem hiding this comment.
@ambient-code We should try to unify the location of all of our documentation to ensure consistency and the ability to serve these docs later. We can refer to the Ambient Code project on GitHub, which uses the docs/internal directory to store internal documentation such as specs and ADRs.
There was a problem hiding this comment.
Updated the location table to point both JEPs and ADRs to the docs/internal/ directory (docs/internal/jeps/ and docs/internal/adr/ respectively). Also updated all file path references throughout JEP-0000, the template, and the README to reflect the new unified location.
jeps/JEP-0000-jep-process.md
Outdated
|
|
||
| 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). |
There was a problem hiding this comment.
@ambient-code Let's clartify that the JEP number is just an incrementing integer, not reflective of the PR#.
| 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 |
There was a problem hiding this comment.
@ambient-code We should always merge the JEPs as PRs so the Markdown documentation is incorporated directly into the Jumpstarter docs/source.
jeps/JEP-0000-jep-process.md
Outdated
| 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 |
There was a problem hiding this comment.
@ambient-code Let's clarify that the rejected JEPs will not be accepted as PRs, but if there is an architectural reason to merge them, then we can merge them with a "Rejected" status.
jeps/JEP-NNNN-template.md
Outdated
| document is preferred (e.g., attaching to an issue or linking from one). | ||
| Use this template to create your JEP. Copy it to a new file named | ||
| JEP-NNNN-short-title.md (where NNNN will be the PR number) and open a | ||
| pull request against the main branch. |
There was a problem hiding this comment.
@ambient-code Let's add some claude/cursor rules to help out with this process of generating JEPs/ADRs and filling out the initial template, choosing the number, etc.
- 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>
2 participants
No description provided.