In this document, all text in a "Tip" block (or inline text with with a ":bulb:" on either side) MUST be removed and/or replaced with text appropriate to this JEP before submission.

Sections may include additional help and advice in comments. ":bulb:" entries in comments only need to be filled in if that text is uncommented.

See JEP-1 for full and accurate description of the JEP process and what is required in each section.

BDFL-Delegate is uncommented by default. As part of the in initial conversation or the JEP submission the sponsor should look for a BDFL Delegate. While not required, it is better for the community if Delegates perform most reviews. If no suitable BDFL-Delegate can be found, that row may be commented out.

Give a short (200 word) description of the technical issue addressed.

• Use present tense - describe what the proposal "does" (as if it were already done), not what it will do.

• Do not go into technical details and instead put those in the Specification section.

• Do not talk about history or why this needs to be done. Instead, add the history to the Motivation section.

Explain why the existing code base or process is inadequate to address the problem that the JEP solves. This section may also contain any historical context such as how things were done before this proposal.

• Provide a clear description of the high-level problem you are trying to solve.

• The problem statement should be written in terms of a specific symptom that affects users, contributors, or the project as a whole.

• The problem statement should not be written in terms of the solution.

• Do not discuss design choices or alternative designs that were rejected - those belong in the Reasoning section.

Explain why particular design decisions were made. Describe alternate designs that were considered and related work. For example, how the feature is supported in other systems. Provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

• Use sub-headings to organize this section for ease of readability.

• Provide a clear description of the cause of the problem.

• Provide a clear description of the high-level solution you have chosen and how it addresses the cause of the problem.

• If there were other possible solutions that you considered and rejected, mention those along with the corresponding reasoning.

• Do not describe implementation details; these should go into the Specification section instead.

• Do not talk about history or why this needs to be done - that is part of Motivation section.

Provide a detailed specification of what is being proposed. Be as technical and detailed as needed to allow new or existing Jenkins developers to reasonably understand the scope/impact of an implementation.

• Use present tense - describe what the proposal "does" (as if it were already done), not what it will do.

• Do not discuss alternative designs that were rejected - those belong in the Reasoning section.

• Avoid in-depth discussion or justification of design choices - that belongs in the Reasoning section.

Describe any incompatibilities and their severity. Describe how the JEP proposes to deal with these incompatibilities.

If there are no backwards compatibility concerns, this section may simply say: There are no backwards compatibility concerns related to this proposal.

Describe the work that needs to be done, if any, to adapt consumers to the proposed change.

Conventional wisdom is that at least three consumers should exist to validate the design of an API; with only one consumer the API probably won’t support another consumer, and with two consumers the API will probably only support more consumers with difficulty (see "The Rule of Threes" in Will Tracz’s Confessions of a Used Program Salesman, Addison-Wesley, 1995).

Completing this section of the JEP involves quantifying the number of consumers that need to be adapted (the cost) and the expected value after adapting these consumers (the benefit). Since the Jenkins project has thousands of individual components, attempting to adapt too many consumers tends to reach a point of diminishing returns. On the other hand, adapting too few consumers risks not only violating the Rule of Threes but also introducing technical debt to the project in the form of incomplete migrations. These incomplete migrations can in turn significantly delay the delivery of future JEPs.

In describing the work that needs to be done to adapt consumers, this section should include a cost-benefit analysis and describe a rational approach to the migration that balances short-term deliverability against long-term maintainability.

Typically, migrations should cover a large portion of the top 200 plugins and/or the plugins in the Bill of Materials (BOM), as the overall health of the Jenkins project is contingent on the health of these popular plugins to a large degree. When in doubt, begin the cost-benefit analysis with this general example and then determine if the calculus needs to be adjusted for the particular case in question.

While not all consumers need to be fully migrated, the scope of the migration does need to be fully quantified in order for the design to stand on its own.

If consumers do not need to be adapted to this change, this section may simply say: There are no migration concerns related to this proposal.

Describe the security impact of this proposal. Outline what was done to identify and evaluate security issues, discuss potential security issues and how they are mitigated or prevented, and detail how the JEP interacts with existing elements in Jenkins, such as permissions, authentication, authorization, etc.

If this proposal will have no impact on security, this section may simply say: There are no security risks related to this proposal.

Describe any impact on the Jenkins project infrastructure.

Include any additions or changes, interactions with existing components, potential instabilities, service-level agreements, and responsibilities for continuing maintenance. 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 this proposal will have no impact on infrastructure, this section may simply say: There are no new infrastructure requirements related to this proposal.

If the JEP involves any kind of behavioral change to code (whether in a Jenkins product or backend infrastructure), give a summary of how its correctness (and, if applicable, compatibility, security, etc.) will be tested.

In the preferred case that automated tests will be developed to cover all significant changes, simply give a short summary of the nature of these tests.

If some or all of the changes will require human interaction to verify them, explain why automated tests are considered impractical. Then, summarize what kinds of test cases might be required: user scenarios with action steps and expected outcomes. Detail whether behavior might be different based on the platform (operating system, servlet container, web browser, etc.)? Are there foreseeable interactions between different permissible versions of components (Jenkins core, plugins, etc.)? Does this change require that any special tools, proprietary software, or online service accounts to exercise a related code path (e.g., Active Directory server, GitHub login, etc.)? When will you complete testing relative to merging code changes, and might retesting be required if other changes are made to this area in the future?

If this proposal requires no testing, this section may simply say: There are no testing issues related to this proposal.

Link to any open source reference implementation of code changes for this proposal. The implementation need not be completed before the JEP is accepted, but must be completed before any JEP is given "Final" status.

JEPs which will not include code changes may omit this section.

Provide a clear description of the high-level tasks needed to productize the prototype implementation. Ideally these tasks would be turned into work items in an issue tracking system (ITS) like Jira or GitHub Issues. As a general rule, it should be possible to complete each task within 1-3 days; if a task takes a week or longer, it has not been broken down with enough granularity. If these tasks are not obvious, then the prototype is not complete enough. Also describe the general roles needed to perform these tasks. For example, is the task well-suited to a new contributor, or does the task require advanced experience in the Jenkins project that demands a seasoned expert? Perhaps the task is well-suited to contributors with an affinity for e.g. frontend development, security, or DevOps. Finally, describe the nature of the work in relation to time: can these tasks be picked up in parallel by any interested volunteers, or do they need to be done in some specific order? Do any tasks depend on other tasks in a way that would serialize the implementation of the project?

JEPs that do not include a prototype implementation may omit this section.

Provide links to any related documents. This will include links to discussions on the mailing list, pull requests, and meeting notes.