Skip to content

Commit 0739b61

Browse files
blink1073blink1073
authored
Merge pull request #52 from choldgraf/new-jep-process
updating with new JEP process
2 parents 9a608e8 + e32a811 commit 0739b61

File tree

4 files changed

+284
-45
lines changed

4 files changed

+284
-45
lines changed

‎.github/pull_request_template.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
✨Proposing a new JEP?✨
2+
3+
Make sure that you have at least done the following:
4+
5+
1. **Create a GitHub issue** in the Jupyter Enhancement Proposals repo that
6+
1. Briefly outlines the proposal
7+
2. Suggests a review team (optional)
8+
3. Declares why it should be a JEP (See the “JEP / Not-a-JEP Rubric” below.)
9+
2. **Identify a Shepherd** to see the process through. (Shepherds are assigned
10+
on a round-robin basis from a set of interested engaged volunteers).
11+
3. **Decide if it's a JEP** according to the criteria listed above. The Shepherd decides if the JEP criteria have been met.
12+
4. **Used the new JEP markdown template** to help structure your thoughts. You can find it in `jupyter-enhancement-proposal-guidelines/TEMPLATE.md` in this repository.

‎README.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,14 @@ Below is a list of JEPs that have been submitted. To view the discussion around
2525
| 0025 | Completed | [Enterprise Gateway](https://github.com/jupyter/enhancement-proposals/pull/25) |
2626
| 0026 | **Submitted** | [Add Language Server Support to Jupyter Server and jupyterlab-monaco](https://github.com/jupyter/enhancement-proposals/pull/26) |
2727
| 0028 | **Submitted** | [Standalone Jupyter Server](https://github.com/jupyter/enhancement-proposals/pull/28) |
28-
| 0029 | **Submitted** | [Jupyter Enhancement Proposal updates](https://github.com/jupyter/enhancement-proposals/pull/29)
28+
| 0029 | **Accepted** | [Jupyter Enhancement Proposal updates](https://github.com/jupyter/enhancement-proposals/pull/29)
2929
| 0042 | **Accepted** | [Voila Incorporation](https://github.com/jupyter/enhancement-proposals/pull/42)
3030

3131
## How do I submit a JEP?
3232

33-
In order to submit a JEP, please read the [Jupyter Enhancement Proposal Submission Guidelines](jupyter-enhancement-proposal-guidelines/jupyter-enhancement-proposal-guidelines.md). You can copy this file and use it as the starting point for outlining your own JEP.
33+
In order to submit a JEP, first read the [Jupyter Enhancement Proposal Submission Guidelines](jupyter-enhancement-proposal-guidelines/jupyter-enhancement-proposal-guidelines.md) which describes the JEP process.
34+
35+
In addition, read
36+
[the JEP proposal template](jupyter-enhancement-proposal-guidelines/JEP-TEMPLATE.md)
37+
for guidance on the questions you should answer before officially submitting
38+
the JEP.

‎jupyter-enhancement-proposal-guidelines/JEP-TEMPLATE.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: <your-JEP-title>
3+
authors: <list-of-authors>
4+
issue-number: <pre-proposal-issue-number>
5+
pr-number: <proposal-pull-request-number>
6+
date-started: <yyyy-mm-dd>
7+
---
8+
9+
# Summary
10+
11+
One paragraph explanation of the proposal.
12+
13+
# Motivation
14+
15+
Why are we doing this? What use cases does it support? What is the expected outcome?
16+
17+
# Guide-level explanation
18+
19+
Explain the proposal as if it was already implemented and you were
20+
explaining it to another community member. That generally means:
21+
22+
- Introducing new named concepts.
23+
- Adding examples for how this proposal affects people's experience.
24+
- Explaining how others should *think* about the feature, and how it should impact the experience using Jupyter tools. It should explain the impact as concretely as possible.
25+
- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
26+
- If applicable, describe the differences between teaching this to existing Jupyter members and new Jupyter members.
27+
28+
For implementation-oriented JEPs, this section should focus on how other Jupyter
29+
developers should think about the change, and give examples of its concrete impact. For policy JEPs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms.
30+
31+
# Reference-level explanation
32+
33+
This is the technical portion of the JEP. Explain the design in
34+
sufficient detail that:
35+
36+
- Its interaction with other features is clear.
37+
- It is reasonably clear how the feature would be implemented.
38+
- Corner cases are dissected by example.
39+
40+
The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.
41+
42+
# Rationale and alternatives
43+
44+
- Why is this choice the best in the space of possible designs?
45+
- What other designs have been considered and what is the rationale for not choosing them?
46+
- What is the impact of not doing this?
47+
48+
# Prior art
49+
50+
Discuss prior art, both the good and the bad, in relation to this proposal.
51+
A few examples of what this can include are:
52+
53+
- Does this feature exist in other tools or ecosystems, and what experience have their community had?
54+
- For community proposals: Is this done by some other community and what were their experiences with it?
55+
- For other teams: What lessons can we learn from what other communities have done here?
56+
- Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.
57+
58+
This section is intended to encourage you as an author to think about the lessons from other languages, provide readers of your JEP with a fuller picture.
59+
If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other languages.
60+
61+
62+
# Unresolved questions
63+
64+
- What parts of the design do you expect to resolve through the JEP process before this gets merged?
65+
- What related issues do you consider out of scope for this JEP that could be addressed in the future independently of the solution that comes out of this JEP?
66+
67+
# Future possibilities
68+
69+
Think about what the natural extension and evolution of your proposal would
70+
be and how it would affect the Jupyter community at-large. Try to use this section as a tool to more fully consider all possible
71+
interactions with the project and language in your proposal.
72+
Also consider how the this all fits into the roadmap for the project
73+
and of the relevant sub-team.
74+
75+
This is also a good place to "dump ideas", if they are out of scope for the
76+
JEP you are writing but otherwise related.
77+
78+
If you have tried and cannot think of any future possibilities,
79+
you may simply state that you cannot think of anything.
80+
81+
Note that having something written down in the future-possibilities section
82+
is not a reason to accept the current or a future JEP; such notes should be
83+
in the section on motivation or rationale in this or subsequent JEPs.
84+
The section merely provides additional information.

‎jupyter-enhancement-proposal-guidelines/jupyter-enhancement-proposal-guidelines.md

Lines changed: 181 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,199 @@
11
# Jupyter Enhancement Proposals (JEP) Guidelines
22

3-
## Problem
4-
Enhancements to the Jupyter ecosystem are currently presented across a multitude of platforms without any centralized management or discussion.
3+
**Note**: This JEP repo is the **canonical "source of truth"** for individual JEPs,
4+
the JEP process, and activity on JEPs.
55

6-
## Proposed Enhancement
6+
## Goals of the JEP process
77

8-
Jupyter Enhancement Proposals will be used when presenting changes or additions that affect multiple components of the Jupyter ecosystem. These changes can include things like:
9-
* Additions/changes to the message spec
10-
* API design that is consumed and produced in several contexts (e.g. the notebook kernel API)
11-
* The notebook format
8+
Project Jupyter uses the Jupyter Enhancement Proposal process (JEP)
9+
to address distributed collaboration and experimentation.
10+
The primary guiding principle of the JEP process is to
11+
encourage collaboration and discussion as early as possible in the lifecycle
12+
of a major proposed change in Jupyter, with the goal of preventing costly rework,
13+
competing ideas, and unnecessary forking or fragmentation of ideas.
1214

13-
The format of this README is itself a JEP and can be duplicated for the creation of further JEPs.
15+
Several sub-goals exist for this process:
1416

15-
## Detail Explanation
17+
- **Maximize success of large proposals** that get stalled in the wrong venue (e.g. a single PR comment thread)
18+
- Provide a **better alternative to “piecemeal” development** where multiple PRs
19+
to build an end-to-end set of functionality are split across multiple GitHub
20+
project without broad consensus, context, or guidance.
21+
- Provide a **clear, time-limited, and authoritative process for work proposals**,
22+
to facilitate funding conversations. (e.g. provide a concrete artifact to reference
23+
in a grant proposal, roadmap item, etc.)
24+
- Provide a **consolidated “stream” of all proposals across the entire Jupyter community**
25+
that contributors of all levels can monitor and selectively engage in.
1626

17-
### JEP Titles
27+
## Tenets of the JEP process
1828

19-
Jupyter Enhancement Proposals will be submitted with a title that is no longer than 12-words long. A JEP is uniquely identified by its title and the pull request number associated with it.
29+
The JEP process operates under the following tenets:
2030

21-
### JEP Labels
31+
- **The JEP process is intended for changes of non-trivial scope.**
32+
“Non-trivial” is addressed below in the “JEP / Not-a-JEP Rubric” of this document.
2233

23-
The pull-request submitted with each JEP will be labeled with the following labels for easy searching:
24-
* `accepted` — this JEP has been accepted and is currently being implemented
25-
* `implemented` — this JEP has been implemented
26-
* `rejected` - this JEP has been rejected and will not be implemented
27-
* `withdrawn` - this JEP has been withdrawn by the submitter but can be re-submitted if someone is willing to champion it
28-
* `active` - this JEP is currently under active discussion within the community
34+
- **The JEP process naturally complements the PR process, but does not replace it.**
35+
A thoroughly-reviewed and approved JEP is a valuable reference during a PR to
36+
reduce friction, reduce time-consuming context sharing, and encapsulate decisions
37+
and other discussions. Moving a premature PR into a JEP should be a lightweight
38+
process that doesn’t cause friction for the contributor.
2939

30-
### JEP Structure
40+
For example, GitHub issue and PR templates across the entire Jupyter project should have
41+
references to the JEP process as a possible outcome of a given PR.
3142

32-
When submitting an enhancement proposal, individuals will include the following information in their submission.
43+
- **There is one JEP repository, all Jupyter-governed projects must use it.**
44+
To faciliate the easiest possible adoption and high visibility of ideas, a
45+
single JEP repository will be used. Even if a JEP only applies to a single organization.
3346

34-
1. The problem that this enhancement addresses. If possible include code or anecdotes to describe this problem to readers.
35-
2. A brief (1-2 sentences) overview of the enhancement you are proposing. If possible include hypothetical code sample to describe how the solution would work to readers.
36-
3. A detailed explanation covering relevant algorithms, data structures, an API spec, and any other relevant technical information
37-
4. A list of pros that this implementation has over other potential implementations.
38-
5. A list of cons that this implementation has.
39-
6. A list of individuals who would be interested in contributing to this enhancement should it be accepted.
47+
- The JEP process **has multiple valid use cases**. Each use case might have a
48+
slightly different expected workflow. Some expected use cases include:
4049

41-
### JEP Submission Process
42-
1. Create a [Markdown](https://help.github.com/articles/github-flavored-markdown/) write up of the problem, proposed enhancement, detailed technical explanation, pros and cons, and interested contributors of the enhancement you are proposing.
43-
2. Create a fork of this repository.
44-
3. Create a folder with its name set to the JEP title in lower snake-case.
45-
3. Place the markdown file created in step 1 and any supplemental materials in that folder.
46-
4. Submit a pull request to the main repository with your JEP.
47-
5. Once your PR is accepted, it will be labeled `active` per the guidelines above.
48-
6. Your JEP will be added to the JEP Index file in this repository.
50+
- Non-trivial feature proposals within a single component that would benefit from
51+
process. (e.g., a non-trivial change to JupyterLab that would benefit from
52+
formal process within the JupyterLab project)
53+
- Non-trivial features or improvements that span multiple projects.
54+
- Any proposed changes to published APIs or core specifications (e.g., nbformat)
55+
- Changes to the JEP process itself.
56+
- Launching a major project in one of the Jupyter GitHub organizations.
4957

50-
## Pros and Cons
5158

52-
Pros associated with this implementation include:
53-
* A higher quality discussion around enhancement proposals
54-
* Individuals are encourage to put more thought into an enhancement proposal before submitting it
55-
* Precedence exists in the form of PEPs (Python Enhancement Proposals) and IPEPs (IPython Enhancement Proposals)
59+
## JEP Submission Workflow
60+
61+
The following sections describe the major checkpoints in the JEP process.
62+
Note that at any time, the JEP author may withdraw their JEP (and if it has
63+
been added to the README, its status becomes "withdrawn").
5664

57-
Cons associated with this implementation include:
58-
* Existing IPEPs (IPython Enhancement Proposals) will not be included in this migrated repository
65+
### Phase 1: Pre-proposal
66+
67+
This is the least formal stage of any jupyter enhancement proposals. During this
68+
phase, discussions on the mailing list, community forum, in-person, on github issues
69+
are all fine to gauge community interest, feasibility, consequences, and to
70+
scope out technical impact and implementation details.
71+
72+
In order to transition out of the pre-proposal stage, the following checklist must be complete:
73+
74+
1. **Create a GitHub issue** in the Jupyter Enhancement Proposals repo that
75+
1. Briefly outlines the proposal
76+
2. Suggests a review team (optional)
77+
3. Declares why it should be a JEP (See the “JEP / Not-a-JEP Rubric” below.)
78+
2. **Identify a Shepherd** to see the process through. (Shepherds are assigned
79+
on a round-robin basis from a set of interested engaged volunteers).
80+
3. **Decide if it's a JEP** according to the criteria listed above. The Shepherd decides if the JEP criteria have been met.
81+
82+
**If it's a JEP**. The JEP author creates a new PR with the contents of the JEP proposal. See [this markdown template](JEP-TEMPLATE.md) for a suggested structure of the pull-request.
83+
84+
Subsequent discussion and decisions about the JEP will happen in that PR, and
85+
we now **Move to the RFC phase**.
86+
87+
**If it’s not a JEP**. The shepherd provides a reason for why the issue
88+
doesn't meet JEP criteria, and closes the issue.
89+
90+
### Phase 2: Request for Comments for the JEP
91+
92+
Phase two begins when **the JEP author submits a draft of the JEP as a PR to the JEP repository**.
93+
The Shepherd assigns a number to the JEP according to the pull-request number, and updates
94+
the README of the JEP repository with information about the now in-progress JEP.
95+
The Shepherd then works with the JEP author to
96+
**identify and notify relevant individuals in the Jupyter community to review and comment**.
97+
98+
Once this group has been notified, the JEP process enters the RFC phase.
99+
100+
During the **Request For Comment (RFC) phase**, the proposal is iterated on with
101+
feedback from the Review Team and the community at large. The Shepherd helps engage
102+
the Review Team and encourage productive discussion. After the Review Team members
103+
have signed off on the JEP, with the criteria that there are no major objections,
104+
and at least some of the Review Team are in favor, the Shepherd initiates the Final Comment Period.
105+
106+
In the **Final Comment Period (FCP)**, the community at-large has at least 10 calendar days
107+
to provide any final comments on the JEP. A JEP may revert back to RFC if
108+
objections from the community are supported by the Review Team.
109+
110+
At the end of the FCP, the JEP is either:
111+
112+
* **approved**, in which case the PR is merged and work may commence on implementing the JEP (see Phase 3, below)
113+
* **rejected**, in which case the PR is closed
114+
* asked to return to the RFC phase.
115+
116+
In each case, the JEP's status should be updated in the README of the
117+
`enhancement-proposals` repository.
118+
119+
### Phase 3: Work Commences
120+
121+
Once a JEP has been merged into the `jupyter/enhancement-proposal` repository,
122+
implementation can commence on the JEP. The JEP author does not need to implement the JEP themselves.
123+
124+
If the JEP requires one or more pull-requests to be implemented, the author of the PRs should
125+
provide a reference to the JEP so that reviewer has background context on the JEP.
126+
As the JEP is being implemented, the JEP text should be amended with with addendums to
127+
denote the progress of the implementation using the following stages.
128+
129+
1. In progress implementation via (list of PRs).
130+
2. Fully implemented via (list of PRs).
131+
132+
If in the course of implementation, it is discovered that the implementation needs to
133+
be radically different from what was defined in the original JEP, then a pull
134+
request is submitted to modify the original JEP with the new necessary implementation,
135+
and a note citing the need for a modification to the JEP.
136+
This pull request should be re-approved by the original review team.
137+
138+
### JEP Pathways and Status
139+
140+
Below is a rough guide that describes the JEP process and its possible pathways.
141+
142+
```
143+
+-----------+
144+
| |
145+
| withdrawn |
146+
| | +-----------+
147+
+-----------+ | |
148+
JEP may be withdrawn | rejected |
149+
at any stage | |
150+
+-----^-----+
151+
|
152+
+------+------+
153+
+--------------+ +-----------+ | | +-------------+ +-----------+
154+
| | | | | Request for | | | | |
155+
| pre-proposal +---> submitted +-------------> Comments +------------> in progress +---> completed |
156+
| | | | identify | (RFC) | approved | | | |
157+
+--------------+ +-----------+ review | | +-------------+ +-----------+
158+
team +------+------+
159+
```
160+
161+
162+
## What qualifies as a JEP?
163+
164+
This section contains a set of principles to help determine when something is a JEP.
165+
These should be used to determine when something becomes a PR during the JEP
166+
pre-proposal stage, as well as to determine when a PR becomes a JEP at an individual repo level.
167+
168+
**Principles to follow**
169+
170+
Below are a few example guidelines to follow when deciding if an idea should include
171+
a JEP (If yes, it requires a JEP). Under each question is a relevant example proposal.
172+
173+
- Does the proposal/implementation require PRs across multiple orgs?
174+
- **Example:** Defining a unique cell identifier
175+
- Does the proposal/implementation PR impact multiple orgs, or have widespread community impact?
176+
- **Example:** Updating nbformat
177+
- Does the proposal/implementation change an invariant in one or more orgs?
178+
- **Example:** Defining a unique cell identifier
179+
- **Example:** Deferred kernel startup
180+
- Does the proposal/implementation create a new concept that will impact multiple repositories?
181+
- **Example:** Sandboxed cell outputs
182+
- Does the proposal involve creating a new repository or sub-project?
183+
184+
## The JEP public archive
185+
186+
A public website contains a readable archive of all JEP proposals.
187+
It contains list of all JEPs that have entered a "final" state
188+
(e.g., "Completed", "Withdrawn", "Rejected"). The content of each JEP will
189+
be displayed in a readable fashion. When a JEP enters into a final state, it
190+
is added to this website.
191+
192+
Note that the JEPs themselves contain the content, while the website is just a
193+
quick way to display them in a reading-friendly format.
194+
195+
## Background
196+
197+
For a background of the JEP process, and recent efforts to improve it, see
198+
[the meta-JEP readme](../29-jep-process/README.md).
59199

60-
## Interested Contributors
61-
@captainsafia, @rgbkrk

0 commit comments

Comments
 (0)