jenkins-infra
/
iep
mirror of https://github.com/jenkins-infra/iep
1
0
Fork 0
Code Issues Releases Wiki Activity
iep/iep-001
History
R. Tyler Croy 95cd2fda79
Add a simple template.adoc based off IEP-001 for copy-pasting 		2016-11-16 11:07:23 -08:00
..
README.adoc Add a simple template.adoc based off IEP-001 for copy-pasting 2016-11-16 11:07:23 -08:00

README.adoc

<html lang="en"> <head> </head>

IEP-1: Infra Enhancement Proposal Format

Table 1. Metadata

IEP

1

Title

Infra Enhancement Proposal Format

Author

R Tyler Croy

Status

📜 Complete

Type

Process

Created

2016-10-25

What is an IEP?

IEP ("eep!") stands for Infrastructure Enhancement Proposa. An IEP is a design document providing information to the Jenkins community, or describing an addition/change to the Jenkins project’s infrastructure. The IEP should provide a concise technical specification of the addition/change and a rationale for the addition/change.

We intend IEPs to be the primary mechanism for major infrastucture proposals, collecting feedback on the proposals, and for documenting the design decisions that have gone into the infrastructure over time. The IEP author is responsible for building consensus among the infrastructure team members, informing the users of the infrastructure and documenting dissenting opinions.

Because the IEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal [1]

IEP Types

  1. Architectural change — an architecture change describes a new way of delivering a service or services for the Jenkins project infrastructure.

  2. Services change — this IEP would describe a new service being added to the infrastructure or changing how an existing service is deployed

  3. Process change — describes a change to how some process for the Jenkins project, or an introduction of a new process to improve the efficiency, transparency or some other quality to the operation of project infrastructure.

IEP Workflow

Start with an idea for infrastructure

The IEP process begins with a new idea for Jenkins project infrastructure. It is highly recommended that a single IEP contains a single key proposal or new idea. Small changes often don’t need a full-fledged IEP document and can simply be contributed as Puppet or other code to the infrastructure workflow.

Each IEP must have a champion — someone who writes the IEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The IEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is IEP-worthy by discussing it first on the infra mailing list.

Once the champion has asked the infra community whether an idea has any chance of acceptance, a draft IEP should be authored and linked to the mailing list. This gives the author the chance to flesh out the draft and its ideas before taking the time to formally submit the proposal.

Submitting an IEP

Following a discussion on the infra mailing list, the proposal should be submitted as a draft IEP via a GitHub pull request to the IEP repository [1]

The standard IEP workflow is:

  • You, the IEP author, fork the IEP repository [1], and create a directory named iep-xxx that contains a README.adoc which is the IEP document. Replace xxx with an incremental IEP number (e.g. 002)

  • Push this to your GitHub fork and submit a pull request.

  • The IEP editors review your PR for structure, formatting, and other errors. Once the IEP editors have reviewed the basic formatting, they will attach the "draft" label to the pull request.

IEP authors are responsible for collecting community feedback on a IEP before submitting it for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided.

Strategies to keep the discussions efficient include: setting up a separate mailing list for the topic, having the IEP author accept private comments in the early design phases, setting up a wiki page, etc. IEP authors should use their discretion here.

The IEP author is responsible for updating the pull request with appropriate changes based on these discussions.

IEP Maintenance

In general, IEPs won’t change over time but rather be superceded by follow-up or new prooposals. Once a proposal has been accepted and implemented, the IEP should stand the test of time as a reference document for future infrastructure contributors.

Process IEPs 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 IEP being updated.

Creating a successful IEP

Each IEP should have the following parts:

  1. Preamble — an AsciiDoc table containing meta-data about the IEP including the number, a short descriptive title (limited to a maximum of 50 characters), the names, and optionally the contact info for each author, etc.

  2. Abstract — a short (200 word) description of the technical issue being addressed.

  3. Specification — The technical specification should describe the requirements, architecture and design of the proposal.

  4. Motivation — The motivation is critical for IEPs that want to add new services to the Jenkins project’s infrastructure. It should clearly explain what benefit to the project the service brings, identifying the problems it solves or the features it offers to the users or developers of the Jenkins project. IEP submissions without sufficient motivation may be rejected outright.

  5. Rationale — The rationale fleshes out the specification by describing what motivated the design and 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 languages. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

  6. Costs — The costs of making this change - these can be financial costs associated with new hosting, and/or organisational costs that will be borne by Jenkins users/teams as part of this change.

  7. Reference Implementation — The reference implementation must be completed for new services or process changes. This could be as succinct as the code repository containing a new application, or an example project demonstrating a new process change. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving discussions about a service’s architecutre or implementation details.

IEP Formats and Templates

IEPs 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.

IEP Header Preamble

Each IEP must begin with an AsciiDoc table containing meta-data relevant to the IEP.

.Metadata
[cols="2"]
|===
| IEP
| 1

| Title
| Infra Enhancement Proposal Format

| Author
| link:https://github.com/rtyler[R Tyler Croy]

| Status
| :speech_balloon: In-process

| Type
| Process

| Created
| 2016-10-25
|===

  1. IEP — Proposal number, use a monotonically increasing number, starting from the latest merged IEP document

  2. Title — Brief title explaining the proposal in fewer than 50 characters

  3. Author — Author/champion of the IEP, in essence, the individual responsible for seeing the IEP through the process.

  4. Status — In-process, Accepted, or Rejected. IEPs should be authored with an In-process status.

  5. Type — Describes the type of IEP: Architectural, Service, Process

  6. Created — Date (%Y%m%d) when the document was first created.

Additional Files

IEPs may include additional files such as diagrams and code snippets. Such files should be added into the iep-xxx/ directory with self-explanatory file names.

IEP Rejection

If an IEP is rejected, the pull request for the IEP should still be merged with additional information added to the header of the document explaining the decision making process and why the proposal was rejected.

This should help in the future when decisions must be revisited or reviewed as tools, technologies and needs of the project change.

1. The source repository for IEPs can be found on GitHub
Last updated 2024-05-04 04:06:36 UTC
</html>