JEP |
1 |
Title |
Jenkins Enhancement Proposal Format |
Sponsor |
|
Status |
Active 😄 |
Type |
Process |
Created |
2017-09-12 |
- Abstract
- Specification
- What is a JEP?
- JEP Types
- JEP Terminology
- JEP Workflow
- Overview
- Start with an idea for Jenkins
- Find a Sponsor
- Discuss the idea with the community
- Creating a JEP Submission
- Approval as Draft JEP
- Refining a Draft JEP
- JEP Review
- Accepting a JEP
- Finalizing a JEP
- JEP Maintenance
- Other JEP Outcomes
- Updating JEP Status and Resolution
- Scheduling and timeframes
- Resolving Disputes
- JEP Guidelines
- Reporting JEP Bugs, or Submitting JEP Updates
- Transferring JEP Sponsorship
- JEP Editor Responsibilities & Workflow
- Motivation
- Reasoning
- Backwards Compatibility
- Security
- Infrastructure Requirements
- References
A Jenkins Enhancement Proposal (JEP) is a design document that describes a new feature or aspect of Jenkins itself, or the Jenkins project processes or environment. This JEP describes the structure of JEP documents and details the process by which JEPs are created, submitted, reviewed, finalized, and maintained.
JEP stands for Jenkins Enhancement Proposal. A JEP is a design document that describes a new feature or aspect of Jenkins itself, or Jenkins project, plugin, processes or environment. A JEP provides a concise technical specification of the feature, describes the motivation for the change, and discusses the rationale behind the design.
JEPs are the primary mechanism for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into Jenkins. Each JEP must have at least one Sponsor. The JEP Sponsor is responsible for the JEP overall - building consensus for that JEP within the community, documenting dissenting opinions, coordinating contributors work, and generally ensuring the JEP meets the style, format, and quality guidelines described below. A JEP may also have any number of Contributors who help write, implement, discussion, or offer feedback about the JEP. One contributor might do only one or any combination of these things during any part of the life of a JEP.
Because the JEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal [1].
|
ℹ️
|
For non-text files added to the repository, such as images, the files must be readable with free and open source tools, and should ideally be editable by other contributors. For example, use SVG rather than PSD for vector graphics. |
There are three kinds of JEP:
-
A Standards Track JEP describes a new feature or implementation for Jenkins. It may also describe an interoperability or backwards-compatibility standard which will be supported for the feature in current versions of Jenkins, moving forward.
-
An Informational JEP describes a Jenkins design issue, or provides general guidelines or information to the Jenkins community, but does not propose a new feature. Informational JEPs do not necessarily represent a Jenkins community consensus or recommendation, so users and implementers are free to ignore Informational JEPs or follow their advice.
-
A Process JEP describes a process surrounding Jenkins, or proposes a change to (or an event in) a process. Process JEPs are like Standards Track JEPs but apply to areas other than the Jenkins codebase itself. They may propose an implementation, but not for what would be generally considered the Jenkins codebase; they often require community consensus; unlike Informational JEPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Jenkins development. Any meta-JEP (JEP focusing on the improvement of the Jenkins Enhancement Proposal process) is also considered a Process JEP.
There are several references in this JEP to the "BDFL". This acronym stands for "Benevolent Dictator for Life". The BDFL is a single person whose role in the project is to act as decision maker when a unilateral decision is needed. The responsibilities of the BDFL are:
-
Review JEPs and decide whether they will be accepted
-
Resolve disputes or arguments within the JEP process that cannot be resolved by consensus
-
Delegate their responsibilities to other contributors as neeeded on a per-JEP basis (see BDFL Delegate)
-
Take any other actions as part of the JEP process that they deem best for the Jenkins project
-
Clearly communicate the reasoning for any actions taken or decisions made
-
Refrain from using their power, letting the community self-govern whenever possible
|
|
Under very specific conditions, described in "Resolving Disputes", contributors may ask the Governance Meeting to review a decision by the BDFL. |
For the Jenkins project the BDFL is Kohsuke Kawaguchi, original creator of Jenkins.
The JEP editors are individuals responsible for managing the administrative and editorial aspects of the JEP workflow (e.g. assigning JEP numbers and changing their status). See JEP Editor Responsibilities & Workflow for details. The current editors are:
JEP editorship is by invitation of the current editors. All of the JEP workflow can be conducted via the GitHub JEP Repository [1] and pull requests.
A JEP may have any number of "Contributors" who help write, implement, discuss, or offer feedback about that JEP. One contributor might do only one or any combination of these of these things during any part of the life of a JEP. While we invite contributions by companies or other organizations, contributors listed in a JEP (such as Sponsors or BDFL Delegates below) need to be specific people.
Each JEP has at least one "Sponsor".
The JEP Sponsor is a contributor who is responsible for the JEP throughout its lifecycle. Their responsibilities include:
-
Building consensus for that JEP within the community
-
Documenting dissenting opinions
-
Coordinating contributors' work
-
Ensuring the JEP meets the style, format, and quality guidelines
-
Maintaining the JEP after it is finalized
-
Setting and communicating the schedule as needed
The Sponsor of a JEP may or may not do any of the tasks other contributors do. For example, one sponsor might write large portions of one JEP, while another sponsor might leave the writing to other contributors.
Anyone may be Sponsor for a JEP, though it should be someone familiar enough with Jenkins, the Jenkins project, and the JEP workflow to effectively guide the JEP to completion.
A JEP may have more than one Sponsor, especially after it has been finalized and is being maintained over time. For simplicity, this document uses the singular ("The JEP Sponsor", "a sponsor") when referring the one or more people in the role of "Sponsor" of a JEP.
Sponsors have committer/write access on the JEP repository, but should only approve and merge pull requests for JEPs to which they are assigned.
The BDFL may delegate their responsibilities to another contributor, a "BDFL Delegate" on a per-JEP basis. The BDFL Delegate for a JEP has all the responsibilities of the BDFL within the context of that JEP, except that BDFL Delegate may not delegate to someone else - there is no such thing as a "BDFL Delegate Delegate".
A BDFL Delegate may be selected at any point before the JEP is reviewed. A record of this selection must be available publicly. Any contributor with sufficient technical and organizational experience to make the final decision on that JEP, may offer to be the BDFL’s Delegate for a JEP. If their self-nomination is accepted by the other core contributors and the BDFL, then that contributor will have the authority to accept (or reject) that JEP. The BDFL Delegate for a JEP will be recorded in the "BDFL-Delegate" header in the JEP.
A JEP’s Sponsor may also be the BDFL Delegate for that JEP, taking on the responsibilities of both roles.
If a Delegate wishes to leave a JEP, they may do so at any time by emailing jenkinsci-dev@googlegroups.com. They can also be removed from a JEP by the BDFL. When a BDFL Delegate leaves or is removed from a JEP, the BDFL becomes the reviewer again and may ask someone else to be the BDFL Delegate for that JEP.
BDFL Delegates have committer/write access on the JEP repository, but should only approve and merge pull requests for JEPs to which they are assigned.
The JEP Reviewer is the contributor who will make the final decision whether to accept a JEP. In all cases where this document refers to the "Reviewer", it means "the BDFL or BDFL Delegate that will review this JEP."
JEP documents must follow RFC 2119 which defines key words to "indicate requirement levels". These are listed below:
-
MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
-
MUST NOT This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition of the specification.
-
SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
-
SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
-
MAY This word, or the adjective "OPTIONAL", mean that an item is truly optional.
|
ℹ️
|
When choosing to go counter to SHOULD or SHOULD NOT guidance, the reasons behind that choice SHOULD be documented. |
Before delving into the details of the JEP workflow, let’s take a high-level look at how JEP might go.
-
Initial Discussion - Andrea has an idea for new feature and emails it jenkinsci-dev@googlegroups.com. She discusses the idea with the group, determining that the idea is worth pursuing. She chooses to be the "Sponsor" for this potential JEP. She gathers initial feedback from the community, adjusts her design as needed, records the reasons for design choices, and keeps track of differing views. Kelly, an expert in the area for this JEP, volunteers to be the BDFL Delegate for this JEP.
-
Submission - Andrea writes up the proposal using the JEP document template as a guide. She includes supporting documentation and a minimal prototype implementation sufficient to convey the viability of the design. She submits the JEP to the JEP editors for approval as a Draft JEP. One of the editors checks the submission and determines it is ready to considered as a JEP. They "approve" the submission, assigning the JEP a number, and the submission becomes a "Draft" JEP.
-
Draft Status - While the JEP is a "Draft", Andrea continues to gather feedback, change the proposal, and record the reasoning and differing views. At the same time, she and other contributors continue expanding and refining the prototype implementation as needed to match the current state of the JEP. When Andrea believes the JEP is stable, addresses all major design and scope questions, and represents the consensus of the community, she then asks the Reviewer, in this case the BDFL Delegate Kelly, to review the JEP for Acceptance.
-
Review - Kelly reviews the JEP and any related discussions and implementation. Kelly agrees with Andrea that consensus has been reached regarding the JEP and that the implementation is far enough along to enusure that the design is stable and complete. Kelly marks the JEP as an "Accepted" JEP.
-
Accepted Status - Andrea and other contributors complete all remaining implementation related to the "Accepted" JEP (code, documentation, or other changes).
-
Final Status - When the implementation is complete and all changes have been published or otherwise incorporated into the appropriate code repositories, the JEP status is changed to "Final" (or in some cases "Active"). The JEP is done.
-
Maintenance - At some later date, the JEP may need to be updated with minor changes and clarifications. As Sponsor of the JEP, Andrea makes changes as needed or hands off sponsorship to someone else. Updates follow the same basic JEP workflow. For extensive changes or additions, Andrea will start a whole new JEP instead of updating the original JEP. This new JEP might expand on the orginal or might replace it.
-
Other Outcomes - Not all JEPs will be accepted and finalized. Other possible outcomes include "Rejected", "Deferred", "Withdrawn".
|
❗
|
The above is only a high-level overview of the JEP workflow. The full and complete description of the JEP workflow is provided below. Read the full description below before starting a JEP. |
The JEP process begins with a new idea for Jenkins. A single JEP should contain a single key proposal or new idea. The more focused the JEP, the more successful it tends to be. The JEP editors reserve the right to reject potential JEPs if they appear too unfocused or too broad. If in doubt, sponsors should split their JEP into several well-focused ones.
|
ℹ️
|
Enhancements or patches which have a smaller impact often don’t need a JEP. These can be handled via the regular Jenkins development workflow with a JIRA issue and/or pull request to the appropriate repository. A JEP may still have an accompanying JIRA issue as a placeholder.
This might be useful, for example, if implementation of the JEP is later found to have introduced a bug;
being able to link the |
Each JEP must have a "Sponsor" — someone who writes the JEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The JEP Sponsor should first attempt to ascertain whether the idea is JEP-able. Posting to the jenkinsci-dev@googlegroups.com mailing list is the best way to go about this.
Vetting an idea publicly before going as far as writing a JEP is meant to save the potential sponsor time. Many ideas have been brought forward for changing Jenkins that have been rejected for various reasons. Asking the Jenkins community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the sponsor. Just because an idea sounds good to the sponsor does not mean it will work for most people in most areas where Jenkins is used.
Once the sponsor has asked the Jenkins community whether an idea has any chance of acceptance, a "pre-Draft" JEP should be presented to jenkinsci-dev@googlegroups.com. This gives the sponsor a chance to flesh out the JEP to make sure it is properly formatted, of high quality, and to address initial concerns about the proposal.
Even for "pre-Draft" discussion, sponsors may find it convient to follow the
JEP Submission steps below, including creating a PR,
but state in PR comments that they not yet ready to submit the JEP.
This allows them to use the PR request tools for discussion and modification right away,
and sets them up for a smooth submission process.
In this case, the sponsor only needs to notify @jenkinsci/jep-editors when they are ready to
submit the JEP for approval as Draft.
Following a discussion on jenkinsci-dev@googlegroups.com, the proposal should be turned into as a JEP submission and submitted via a GitHub pull request to this repository [1].
|
❗
|
All submissions must go through pull request, even those by editors or contributors with "git push" privileges for the JEP repository [1]. |
To submit a JEP for approval as Draft, the JEP sponsor should:
-
Fork the JEP repository [1].
-
Clone their forked repository locally.
-
Create a new branch called
jep-submissionin their clone (git checkout -b jep-submission). If there is already a JEP being submitted from this fork, they may uniquify the branch name; for example,jep-submission-JENKINS-nnnnn. -
Copy the folder
jep-template/0000tojep/0000. -
Modify the template JEP in
jep/0000per the instructions in this JEP (which are also outlined in the template). -
Commit and push the changes to their fork and submit a pull request targeting the
jenkinsci/masterbranch. -
Add the following line to the description of the PR to indicate that the JEP is being submitted for approval as draft: "Submitted for approval as draft JEP by
@jenkinsci/jep-editors." If this is a PR that was created earlier to gather feedback, the line requesting approval should be added as a comment when the JEP is ready.
The sponsor may alter the steps above or do something else entirely as long the result is a PR with a submission in the appropriate format with a comment asking for approval as draft.
A JEP editor will check the submission for conformance with JEP structure and formatting guidelines. Editors may make minor changes to make the submission meet the requirements for approval as a Draft JEP. If a JEP requires major changes, editors will add specific feedback and send the submission back to the sponsor for revision.
|
❗
|
"Approval as Draft" is not the same as accepting the JEP. "Approval as Draft" is an initial conformance and viability check. When a sponsor submits a JEP for approval, Editors and contributors should restrict their feedback to issues which would cause the JEP to be denied Draft status. This keeps the approval process from bogging down in details that are outside the scope of evaluating whether a JEP is ready for "Draft" status. |
The JEP editors will not unreasonably deny a JEP "Draft" status. Reasons for denying JEP "Draft" status include:
-
duplication of effort
-
being technically unsound
-
not providing enough information in all Required Sections ("Motivation", "Backwards Compatibility", etc)
-
not in keeping with the Jenkins philosophy.
The Reviewer for this JEP may be consulted during the approval phase, and is the final arbiter of a submission’s approvability as a Draft JEP.
Once JEP meets requirements for structure and formatting,
the editors will approve the submission as a draft JEP
by following the steps outlined in the
editors' "Approve as Draft" section.
When they are done, the Draft JEP will have an official JEP number and
the submission PR will have been merged to a matching folder
(for example,
jep/1)
in the master branch.
Editors are not the only ones who can approve a submission. Non-editor contributors who have "git push" privileges for the JEP repository [1] may also approve submissions. When doing so, that contributor must handle the tasks that would normally be taken care of by the JEP editors (see JEP Editor Responsibilities & Workflow). This includes ensuring the initial version meets the expected standards for a Draft JEP.
The version of a JEP that is approved as a Draft JEP is rarely the same as the final version that is reviewed and hopefully accepted. A Draft JEP often requires further refinement and expansion before it is sufficiently complete and represents the consensus of the community.
Standards Track JEPs consist of two parts, a design document and a prototype implementation. The prototype implementation should be co-developed with the JEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation.
A JEP’s sponsor is responsible for collecting community feedback on a JEP before submitting it for review. Potential changes to a draft JEP may be discussed further on jenkinsci-dev@googlegroups.com. However, long open-ended discussions are not recommended on mailing lists. Strategies to keep the discussion efficient include:
-
setting up a series of in-person, or video-conferencing sessions to discuss the JEP with necessary stakeholders.
-
having the JEP sponsor accept private comments in the early design phases
-
setting up a wiki page, etc.
-
committing and reviewing small concrete changes via Pull Requests rather than large sweeping changes
JEP sponsors should use their discretion here.
The JEP sponsor may also ask JEP editors for further feedback regarding the style and consistency of a JEP and its readiness for review.
As updates are necessary, the JEP sponsor and other contributors
should push commits to their fork of the JEP repository [1],
and submit pull requests targeting the master branch.
Once the sponsor believes a JEP meets at least the minimum criteria to be "Accepted", they request the JEP be reviewed for acceptance, usually via an email to the jenkinsci-dev@googlegroups.com mailing list. The JEP Reviewer and their chosen consultants then review the JEP. If the Reviewer agrees that JEP is ready, they mark the JEP as "Accepted". If they do not agree, they leave the JEP as a "Draft", awaiting further revision. In either case, the reviewer must send a detailed response to the jenkinsci-dev@googlegroups.com mailing list explaining their decision.
JEP review and resolution may also occur on a list other than jenkinsci-dev@googlegroups.com. In this case, the "Discussions-To" header in the JEP will identify the appropriate alternative list where discussion, review and pronouncement on the JEP will occur.
For a JEP to be "Accepted" it must meet certain minimum criteria. It must:
-
provide a net improvement.
-
represent the consensus of the community, including documentation of dissenting opions.
-
clearly define the scope and features of the proposed enhancement.
-
describe a completed design that addesses any major design questions.
For JEPs that include implementation based on the proposal, the implementation must meet certain minimum criteria. It must:
-
be solid and have progressed enough to resolve major design or scope questions.
-
not complicate Jenkins unduly.
-
have the same license as the component the proposal is meant to be added to (or MIT licensed by default).
By marking a JEP as "Accepted" the Reviewer indicates they believe that the JEP has clear scope, design completeness, community consensus, and (if applicable) in-progress implementation. Without all of these a JEP cannot be accepted. For this reason, it is not unusual for JEPs to remain in "Draft" state even after they have strong community support and progressing implementation. They must still pass the other criteria, such as scoping and design completeness.
Once a JEP has been accepted, the implementation must continue to progress and eventually be completed. The Jenkins project values contribution over "talk" [2], and as such the implementation is of utmost importance to moving any proposal (Standards or Process) forward.
Ideally, all changes to a JEP should be completed before it is "Accepted", but surprises may still occur. Changes might be minor changes, such as clarifications or typo fixes, or major changes, which would alter the intent, scope, API, or core behavior of the JEP.
All changes to an already "Accepted" JEP, must be submitted via PR as usual. In the case of major changes, the Sponsor should also communicate those changes on the mailing list and take sufficient time to ensure there is consensus on the changes before merging them. A link to any discussion should be added to the PR for the change and to the References section. If there are significant objections or questions around proposed changes, the JEP Sponsor or Reviewer may choose to return the JEP to a "Draft" status for more extensive discussion and eventual review again for acceptance.
When the implementation is complete and incorporated into the appropriate "main" code repository, the JEP sponsor will change the JEP’s status changed to "Final".
Even after a JEP reaches "Final" status, it may need to be updated.
In general, Standards track JEPs are not modified after they have reached the Final state. Once a Standards JEP has been completed, Jenkins developer documentation must become the formal documentation of the expected behavior.
Informational and Process JEPs may be updated over time to reflect changes to development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the JEP being updated.
- Replaced
-
Final JEPs may eventually also be "Replaced" - superseded by a different JEP - rendering the original obsolete. This is intended for Informational JEPs, where version 2 of an API can replace version 1. When a JEP is marked as replaced, the Superseded-by header must be filled in with a link to the new JEP.
Not all JEPs will be accepted and finalized.
- Rejected
-
A JEP Reviewer may choose to reject a JEP. Perhaps after all is said and done it was not a good idea or perhaps a competing proposal is a better alternative. It is still important to have a record of this fact.
Rejecting a JEP is a very strong statement. If the reviewer believes the JEP might eventually be accepted with sufficient modification, the reviewer will not reject the JEP. If a reviewer is confident JEP will never be accepted, they should inform the JEP sponsor as soon as possible to prevent wasted effort. On the other hand, even an Accepted JEP may ultimately be rejected at some point before it reaches "Final" status, due to factors not known at the time it was Accepted.
Upon the request of the sponsor, the reviewer may choose to return a Rejected JEP to Draft status, but this is at the discretion of the reviewer.
- Withdrawn
-
A JEP Sponsor may choose to withdraw a JEP. Similar to "Rejected", "Withdrawn" means that the JEP sponsor themselves has decided that the JEP is actually a bad idea, or agrees that a competing proposal is a better alternative.
- Deferred
-
A JEP can also be assigned a status of "Deferred". The JEP sponsor or an editor can assign the JEP this status when no progress is being made on the JEP. Once a JEP is deferred, a JEP editor can re-assign it to draft status.
Whenever a JEP status changes, the "Status" field in the JEP document must be updated.
The possible paths of a JEP’s status are as follows:
When a JEP is Accepted, Rejected or Withdrawn, a "Resolution" section must be added to the JEP Header with a link to the relevant post in the jenkinsci-dev@googlegroups.com mailing list archives.
This workflow does not dictate specific time frames for any actions. In general, it is expected that a JEP should make reasonable progress over time, and all involved should respond in everyone can agree is timely manner. If it becomes necessary to set specific timeframes for action, it is the sponsors responsibility to do so. Just as the sponsor must build consensus for a JEP, they must also set and communicate a reasonable schedule to keep a JEP moving forward. If one or more contributors are not responding and the sponsor chooses to move forward without their feedback, they should document that choice in the "Reasoning" section of the JEP.
Except for decisions by a JEP’s Reviewer, the JEP process is run by consensus. It is the responsibility of every contributor to respect other contributors, listen to their perspectives, and attempt to find solutions that work for everyone.
If consensus cannot be achieved on a JEP, contributors may request that the JEP Reviewer intervene. The reviewer will consider the matter, and render their decision, including describing what actions will be taken and documenting their reasoning.
For disputes involving a decision by a BDFL Delegate or the overall JEP process (rather than one specific JEP), contributors may request that the BDFL intervene. The BDFL will consider the matter and render their decision, including describing what actions will be taken and documenting their reasoning. The BDFL’s decision may include technical direction and other specific instructions as needed.
If contributors believe a decision made by the BDFL runs counter to the best interests to Jenkins project, they may request the Governance meeting review the BDFL’s decision. The Governance meeting will take up the matter and render a decision within a reasonable timeframe. Similar to the judiciary, the Governance meeting will not make technical decisions, they will only affirm or reject the BDFL’s decision. If they affirm, the matter is closed. If they reject, the BDFL will render a new decision taking into account the Governance Meeting’s input.
All JEPs MUST have the following parts to be "approved as Draft":
-
Metadata - table containing the JEP Header Preamble about the JEP, including the JEP number, a short descriptive title, the names, and optionally the contact info for each sponsor, etc.
-
Abstract - short (200 word) description of the technical issue being addressed.
-
Specification - The technical specification should describe the syntax and semantics of any new feature. The specification should be sufficiently detailed to allow new or existing Jenkins developers to reasonably understand the scope/impact of an implementation.
-
Motivation - A clear description of the motivation is critical for any JEP that wants to change Jenkins or the Jenkins project. The motivation section should clearly explain why the existing code base or process is inadequate to address the problem that the JEP solves. A JEP submission without sufficient discussion of its motivation will not be approved as a JEP Draft.
-
Reasoning - The reasoning describes why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other systems.
The reasoning section provides evidence of consensus within the community and describes important objections or concerns raised during discussion.
-
Backwards Compatibility - All JEPs must include a section describing any incompatibilities and their severity. The JEP must explain how it proposes to deal with these incompatibilities. If there are no backwards compatibility concerns, the section must say that.
-
Security - All JEPs must include a section describing their security impact. This includes outlining what was done to identify and evaluate security issues, discussion of potential security issues and how they are mitigated or prevented, and how the JEP interacts with existing permissions, authentication, authorization, etc. If the JEP has no impact on security, the section must say that.
-
Infrastructure Requirements - All JEPs must include a section describing their impact on Jenkins project infrastructure, including additions or changes, interactions with exiting components, potential instabilities, service-level agreements, and assigning responsibility for continuing maintenance. Each JEP must explain the scope of infrastructure changes with sufficient detail to allow initial and on-going cost (in both time and money) to be estimated. If the JEP has no impact on infrastructure, the section must say that.
-
Testing - All JEPs which include code changes must include a section summarizing how the changes will be tested. The JEP itself need not include a complete test plan—this could be developed concurrently with the rest of the implementation—but it should set out expectations for testability. If the JEP has no testing needs, the section must say that.
-
Prototype Implementation — If a JEP will include code changes, this section will provide links to a an open source prototype implementation of those changes. The prototype implementation must be present for a JEP to be approved as Refining a Draft JEP. The prototype implementation must be sufficient to convey the viability of the design for a JEP to be Accepting a JEP. While there is merit to the approach of reaching consensus on the specification and reasoning before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details. JEPs which will not include code changes may omit this section.
-
References — When moving a JEP from a Draft to "Accepted" or "Final" state, the references section must be updated to include links to the pull requests and mailing list discussions which were involved in the process. The JEP should self-document the process in which it was developed.
|
|
JEP submissions that do not adequately complete any of the above sections will not be approved as JEP Drafts. |
The final implementation must include test code and documentation appropriate for either the Jenkins user or developer documentation.
JEPs are UTF-8 encoded text files using the AsciiDoc format. AsciiDoc allows for rich markup that is still quite easy to read, but also results in good-looking and functional HTML.
All JEPs MUST begin with an AsciiDoc table containing metadata relevant to the JEP:
.Metadata
[cols="2"]
|===
| JEP
| 1
| Title
| Jenkins Enhancement Proposal Format
| Sponsor
| link:https://github.com/rtyler[R Tyler Croy]
| Status
| Draft :speech_balloon:
| Type
| Process
| Created
| 2017-09-12
|===-
JEP — Proposal number, given by the JEP editors. Use "0000" until one is assigned.
-
Title — Brief title explaining the proposal in fewer than 50 characters
-
Sponsor — Sponsor of the JEP, in essence, the individual responsible for seeing the JEP through the process.
-
Status — Draft 💬, Deferred ⌛, Accepted 👌, Rejected ⛔, Withdrawn ✋, Final 🔒, Replaced 🗡️, Active 😄.
-
Type — Describes the type of JEP: Standards, Informational, Process
-
Created — Date (
%Y-%m-%d) when the document was first created.
- JIRA
-
A JIRA row is available to specify a linked placeholder JIRA issue, if any.
- BDFL-Delegate
-
A [BDFL-Delegate] row records who will make the final decision to approve or reject a JEP. If this row is not included, the BDFL will make the decision.
- Discussions-To
-
For a JEP where final pronouncement will be made on a list other than jenkinsci-dev@googlegroups.com, a Discussions-To row will indicate the mailing list or URL where the pronouncement will occur. A temporary Discussions-To header may also be used when a draft JEP is being discussed prior to submission for pronouncement.
- Requires
-
JEPs may have a Requires row, indicating the JEP numbers that this JEP depends on.
- Superseded-By
-
JEPs may also have a Superseded-By row indicating that a JEP has been rendered obsolete by a later document; the value is the number of the JEP that replaces the current document. The newer JEP must have a Replaces row containing the number of the JEP that it rendered obsolete.
- Resolution
-
A Resolution section will be added to JEPs when their status is set to Accepted, Rejected or Withdrawn. It will include a link to the relevant post in the jenkinsci-dev@googlegroups.com mailing list archives.
The process for reporting a bug or submitting a JEP update depends on several factors, such as the maturity of the JEP, the preferences of the JEP sponsor, and the nature of the comments. For the early draft stages of the JEP, it’s probably best to send comments and changes directly to the JEP sponsor. For more mature, or finished JEPs consider submitting corrections to the JEP repository [1] or the Jenkins issue tracker [3]. If the JEP sponsor is a Jenkins developer, assign the bug/patch to them, otherwise assign it to a JEP editor.
When in doubt about where to send changes, please check first with the JEP sponsor and/or a JEP editor.
Even JEP sponsors with git push privileges for the JEP repository should submit via Pull Request, with the exception of status or resolution updates which may be pushed directly given the change was already discussed and agreed to elsewhere.
It occasionally becomes necessary to transfer sponsorship of JEPs to a new sponsor. In general, it is preferable to retain the original sponsor as a co-sponsor of the transferred JEP, but that’s really up to the original sponsor. A good reason to transfer sponsorship is because the original sponsor no longer has the time or interest in updating it or following through with the JEP process, or has fallen off the face of the 'net (i.e. is unreachable or not responding to email). A bad reason to transfer sponsorship is because the sponsor doesn’t agree with the direction of the JEP. One aim of the JEP process is to try to build consensus around a JEP, but if that’s not possible, a sponsor can always submit a competing JEP.
Ownership of a JEP may also be assumed via pull request. Fork the JEP repository, [1] make the sponsorship modification, and submit a pull request. At the same time, send a message asking to take over, addressed to both the original sponsor and the JEP editors via jenkinsci-dev@googlegroups.com. If the original sponsor doesn’t respond to email in a timely manner, the JEP editors will make a unilateral decision (it’s not like such decisions can’t be reversed :).
A JEP editor must subscribe to the jenkinsci-dev@googlegroups.com list and must watch the JEP repository [1]. Most correspondence regarding JEP administration can be handled through GitHub issues and pull requests.
Aside from the editorial cases outlined below, editors should submit all changes as GitHub pull requests (the same as any other contributor).
|
❗
|
JEP editors don’t pass judgment on JEPs. They merely do the administrative & editorial part (which is generally a low volume task). |
For each new JEP submission, an editor will:
-
Read the JEP to check if it is ready, sound, and complete. The ideas must make technical sense, even if they don’t seem likely to be accepted.
-
The title should accurately describe the content.
-
Edit the JEP for minor non-controversial language (spelling, grammar, sentence structure, etc.), markup, code style changes. For significant or time consuming changes, the editor may choose to provide feedback instead.
If the JEP isn’t ready, an editor will send it back to the sponsor for revision with specific instructions.
Once the JEP is ready for the repository, a JEP editor will assign a JEP number. This will almost always just the next available number, but may also be a special/joke number, like 666 or 3141. The submission PR may be merged as follows:
# Substitute according to details:
NUMBER=232
PR=375
# Now in a checkout of this repo:
git checkout master
git pull
git pull --no-commit --no-ff origin pull/$PR/head
mkdir jep/$NUMBER
git mv jep/0000/README.adoc jep/$NUMBER/README.adoc
perl -p -i -e s/0000/$NUMBER/g jep/$NUMBER/README.adoc
./jep/set-jep-status $NUMBER draft
git add jep
git diff MERGE_HEAD # sanity check
git commit -m "Merged #$PR as JEP-$NUMBER"
git pushEditors add and remove Sponsors and BDFL Delegates from the appropriate permission groups on the JEP repository. When a JEP includes a new Sponsor or BDFL Delegate an editor will add that person to the "JEP Sponsors" or "JEP BDFL Delegates" GitHub group respectively. When someone is no longer an active Sponsor or BDFL Delegate, a JEP editor will remove them from the permission group. Editors will clean up the the permission groups from time to time as they see the need or are asked to do so.
Jenkins has classically been driven by "you-had-to-be-there" development. With specific changes largely being driven by smaller independent groups of developers (sometimes just one).
Design documents extending back into the history of Jenkins are few and far between, as the project grew organically over time. As such, a contributor, existing or future, must read mountains of code, pull requests, mailing list discussions, etc, in order to fully understand how/what/why for many major subsystems within Jenkins.
Additionally, Jenkins has no formal approach to discussing and reviewing larger changes as evidenced by many of the Jenkins 2.0 mailing list threads [4], which ballooned into threads with 100+ replies and sufficient chaos to be very difficult for those who weren’t full-time Jenkins developers to understand.
The Jenkins Enhancement Proposal aims to address both of these major issues by providing an understood process for making sizable, but understandable, enhancements to Jenkins.
JEP provides a systematic approach for vetting and developing new proposals and ideas for Jenkins. By encouraging "everybody to follow the rules" it will be easier for existing developers to get their ideas and changes into Jenkins without finding themselves mired in unspoken cultural norms within the project.
By providing clear, understandable, and bite-sized design documents which would explain various subsections of Jenkins. JEPs also make it clearer how an ambitious new developer to the Jenkins project can propose, and make progress upon, a new idea they have for Jenkins.
Overall, less chaos and more productivity is the rationale for JEP.
The Python community, whose process JEP is modeled after, have successfully navigated several large-scale reworkings of Python and its related tools and processes over the past decade. This includes most notably the multi-year project of Python 3 (formerly Python 3000).
The process by which a number of Apache projects are operated was also considered, but the Python Enhancement Proposal process was by far the most well-documented and obviously successful approach considered to project improvement (technical and otherwise) over time.
The Python process uses "Rationale" as the heading for the section for describing design decisions. However the meaning of "Rationale" is similar to "Motivation" in some contexts. We decided to use "Reasoning" instead to avoid confusion.
Some non-native english speakers commented on the Must/Should/May mentioned that "should" is a synonym of "must", but that existing RFC was a good justification for keeping the terms.
People expressed concern over the limits of the current model where the BDFL has final say in a number of steps. They felt having 1-person bottlenecks in the JEP process could be problematic. The BDFL delegating to others addresses some of that, but it is still worth noting possible alternatives.
One alternative would be for the Jenkins project Governance meeting to have final say. Another alternative would be to create some sort of "Technical Steering Committee", separate from Governance, to do this job.
Issues mentioned in relation to these alternatives:
-
Voting policy - a voting policy would need to be established, outlining what percentage of the meeting would need to vote for or against a JEP.
-
Committee vs Delegation - a strictly committee-approval approach may not result in good decisions being made in a timely manner. For example, only a few people are qualified to make decisions on Remoting. It would be difficult for a group of people in
#jenkins-meetingto vote sensibly on a JEP relating to Remoting which most of them don’t fully understand. Delegation to experts and stakeholders is much more likely to produce high quality improvements. -
Lack of established process - structured technical decision making in the Jenkins project (as outlined in this JEP) is still in its early stages.
The BDFL model with Delegation as needed may not be sufficient in the long run, but it will suffice for now.
Along with concerns about a bottleneck in reviews, some wanted to add specific language to set expectations timeliness (also sometimes referred to a "service-level agreements", or SLAs). The "[Deferred]" status addresses what happens if a sponsor does not move a JEP forward in a timely manner, but there are no contingencies for slow response from contributors, editors, BDFL, or BDFL delegates.
There are any number of ways to set expectations about timeliness. For example, regarding the review process, one person mentioned put forward, this possible outline.
For now, we have chosen to add a "Scheduling and timeframes" section and not to set specific timeframes for action or response. Attempting to set exact limits on a volunteer organization could lead to more difficulties than leaving the timing up to the contributors to each JEP.
Some contributors were concerned that changes to a component "must be the same license as the component the proposal is meant to added to (or MIT licensed by default)." The mentioned that some companies strictly require "Apache v.2", because MIT is not explicit about the patent release. By setting this condition we explicitly require contributors to create at least a prototype implementation with the MIT license, which their employer may not allow.
We could allow other licenses, or mixed licenses. However, most JEPs will refer to core or many of the "essential" plugins. All of those are MIT licensed, such that anybody contributing to those repositories is already expected to contribute under the existing (MIT) license.
We chose to keep this text as-is until we have a concrete reason to change it.
There are a number of possible asciidoc style guidelines. For example, there are a number of reasons to use one sentence per line, one phrase per line, or other specific formatting. However, choosing which guideline to require, recommend, or even make optional, is a potentially long and difficult process. Instead of bogging down this JEP in that process, we decided to consider asciidoc style and formatting guidelines in a later JEP.
There are currently no Asciidoc linters. Should one be found, we will evaluate it for automated checking of JEP File Format for syntax or structural errors (or for style guidelines once they are established).
There are no new infrastructure requirements related to this proposal. This JEP leverages existing infrastructure.