From 48cf6754e1699324107c1eec05f77397263fd6b2 Mon Sep 17 00:00:00 2001 From: Santiago Torres Date: Thu, 4 Oct 2018 20:23:30 -0400 Subject: [PATCH 1/9] ENH: 01: add initial draft --- ITE/1/README.adoc | 925 +++++++++++++++++++++++++++++++++++++++++++++ ITE/1/workflow.png | Bin 0 -> 20813 bytes 2 files changed, 925 insertions(+) create mode 100644 ITE/1/README.adoc create mode 100644 ITE/1/workflow.png diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc new file mode 100644 index 0000000..3c10471 --- /dev/null +++ b/ITE/1/README.adoc @@ -0,0 +1,925 @@ += ITE-1: in-toto Enhancement Format +:source-highlighter: pygments +:toc: preamble +:toclevels: 2 +ifdef::env-github[] +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:warning-caption: :warning: +endif::[] + +.Metadata +[cols="2"] +|=== +| ITE +| 1 + +| Title +| in-toto Enhancement format + +| Sponsor +| link:https://github.com/santiagotorres[Santiago Torres-Arias] + +| Status +| Active :smile: + +| Type +| Process + +| Created +| 2018-10-04 + +|=== + + +[[abstract]] +== Abstract + +An in-toto Enhancement (ITE) is a design document that describes a new feature +or aspect of the in-toto framework, a setup of its supply chain or an, +organizational aspect of the in-toto project. This ITE describes the structure +of ITE documents and details the process by which ITEs are created, submitted, +reviewed, finalized, and maintained. + +[[specification]] +== Specification + +=== What is an ITE? + +ITE stands for in-toto Enhancement. An ITE is a design document that describes +a new feature or aspect of the in-toto framework, the in-toto supply chain, or +the process within in-toto project. An ITE provides a concise technical +specification of the feature, describes the motivation for the change, and +discusses the rationale behind the design. + +ITEs 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 in-toto. Each ITE must have at least one <>. The ITE Sponsor +is responsible for the ITE overall - building consensus for that ITE within the +community, documenting dissenting opinions, coordinating contributors work, and +generally ensuring the ITE meets the style, format, and quality guidelines +described below. An ITE may also have any number of <> who help write, implement, discuss, or offer feedback about +the ITE. One contributor might do only one or any combination of these things +during any part of the life of a ITE. + +Because the ITEs are maintained as text files in a versioned +repository, their revision history is the historical record of the +feature proposal footnoteref:[repo, https://github.com/in-toto/ITE]. + +[NOTE] +==== +For non-text files added to the repository, such as images, the files must be +readable with free or open source tools, and should ideally be editable by +other contributors. For example, use SVG rather than PSD for vector graphics. +==== + +=== ITE Types + +There are three kinds of ITE: + +. A **Standards Track** ITE describes a new feature or implementation + for the in-toto specification. It may also describe an interoperability or + backwards-compatibility standard which will be supported for the feature in + current versions of in-toto, moving forward. +. An **Informational** ITE describes an in-totodesign issue, or + provides general guidelines or information to the in-toto community, + but does not propose a new feature. Informational ITEs do not + necessarily represent a in-toto community consensus or + recommendation, so users and implementers are free to ignore + Informational ITEs or follow their advice. An example of an informational ITE + would be the recommendations for integrating in-toto and TUF. +. A **Process** ITE describes a process surrounding the in-toto proejct, or + proposes a change to (or an event in) a process. Process ITEs are like + Standards Track ITEs but apply to areas other than the in-toto specification + itself. They may propose an implementation, but not for what would be + generally considered the in-toto codebase; they often require community + consensus; unlike Informational ITEs, 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 in-toto development. Any meta-ITE (ITE focusing on the + improvement of the in-toto Enhancement process) is also considered a + Process ITE. + +=== ITE Terminology + +==== Editor + +The ITE editors are individuals responsible for managing the administrative +and editorial aspects of the ITE workflow (e.g. assigning ITE numbers and +changing their status). See <> for +details. + +ITE editorship is by invitation of the current editors. All of the ITE workflow +can be conducted via the GitHub ITE Repository footnoteref:[repo] and pull +requests. Editors are members of a GitHub group called `ITE-editors`. + +==== Contributor + +A ITE may have any number of `Contributors` who help write, implement, discuss, +or offer feedback about that ITE. One contributor might do only one or any +combination of these of these things during any part of the life of a ITE. +While we invite contributions by companies or other organizations, contributors +listed in a ITE need to be specific people. + +==== Sponsor + +Each ITE has at least one "Sponsor". + +The ITE Sponsor is a contributor who is responsible for the ITE throughout its +lifecycle. Their responsibilities include: + +* Building consensus for that ITE within the community +* Documenting dissenting opinions +* Coordinating contributors' work +* Ensuring the ITE meets the style, format, and quality guidelines +* Maintaining the ITE after it is finalized +* Setting and communicating the schedule as needed + +The Sponsor of a ITE may or may not do any of the tasks other contributors do. +For example, one sponsor might write large portions of one ITE, while another +sponsor might leave the writing to other contributors. + +Anyone may be Sponsor for a ITE, though it should be someone familiar enough +with in-toto, the in-toto project, and the ITE workflow to effectively guide +the ITE to completion. + +A ITE 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 ITE Sponsor", "a sponsor") when referring the one or more people +in the role of "Sponsor" of a ITE. + +Sponsors have committer/write access on the ITE repository, but should +only approve and merge pull requests for ITEs to which they are assigned. + +==== Reviewer + +The ITE Reviewer is the contributor who will make the final decision whether to +accept a ITE. In all cases where this document refers to the `Reviewer`, it +means "an editor who will review this ITE." + +[[requirement-levels]] +==== Must/Should/May + +ITE documents _must_ follow link:https://tools.ietf.org/html/rfc2119[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. + +NOTE: When choosing to go counter to SHOULD or SHOULD NOT guidance, +the reasons behind that choice SHOULD be documented. + +=== ITE Workflow + +==== Overview + +Before delving into the details of the ITE workflow, let's take a high-level +look at how ITE might go. + +. **<>** - Andrea has an idea for new feature and emails it in-toto-dev@googlegroups.com. + She discusses the idea with the group, determining that the idea is worth pursuing. + She chooses to be the "<>" for this potential ITE. + She <> 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 ITE, volunteers to be the <> for this ITE. + +. **<>** - Andrea writes up the proposal using the ITE + 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 ITE to the <> for + <>. + One of the editors checks the submission and determines it is ready to considered as a ITE. + They "approve" the submission, assigning the ITE a number, + and the submission becomes a "<>" ITE. + +. **<>** - While the ITE is a "<>", 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 ITE. + When Andrea believes the ITE is stable, addresses all major design and scope + questions, and represents the consensus of the community, she then asks the + <>, in this case the <> Kelly, to review the ITE for + Acceptance. + +. **<>** - Kelly reviews the ITE and any related discussions + and implementation. Kelly agrees with Andrea that consensus has been reached + regarding the ITE and that the implementation is far enough along to enusure + that the design is stable and complete. Kelly marks the ITE as an "<>" ITE. + +. **<>** - Andrea and other contributors + complete all remaining implementation related to the + "<>" ITE (code, documentation, or other changes). The + specification is updated and a reference to this ITE is added. + +. **<>** - When the implementation is complete + and all changes have been published or otherwise incorporated into the + appropriate code repositories, the ITE status is changed to "<>" + (or in some cases "<>"). The ITE is done. + +. **<>** - At some later date, the ITE may need to be + updated with minor changes and clarifications. As <> of the ITE, + Andrea makes changes as needed or hands off sponsorship to someone else. + Updates follow the same basic ITE workflow. For extensive changes or + additions, Andrea will start a whole new ITE instead of updating the original + ITE. This new ITE might expand on the orginal or might <> +it. + +. **<>** - Not all ITEs will be accepted and finalized. + Other possible outcomes include "<>", + "<>", "<>". + +IMPORTANT: The above is only a high-level overview of the ITE workflow. +The full and complete description of the ITE workflow is provided below. +Read the full description below before starting a ITE. + +[[start]] +==== Start with an idea for in-toto + +The ITE process begins with a new idea for in-toto. +A single ITE should contain a single key proposal or new idea. +The more focused the ITE, the more successful it tends to be. +The ITE editors reserve the right to reject potential ITEs +if they appear too unfocused or too broad. +If in doubt, sponsors should split their ITE into several well-focused ones. + +[NOTE] +==== +Enhancements or patches which have a smaller impact often don’t need an ITE. +These can be handled via the regular in-tot development workflow with a GitHub +issue and/or pull request to the appropriate repository. + +An ITE may still have an accompanying GitHub issue as a placeholder. This +might be useful, for example, if implementation of the ITE is later found to +have introduced a bug; being able to link the `regression`-labelled GitHub issue +to the placeholder is valuable for tracking purposes. In such a case be sure +to specify a "<>" section. + +==== + +==== Find a Sponsor + +Each ITE must have a "<>" -- someone who writes the ITE using the +style and format described below, shepherds the discussions in the appropriate +forums, and attempts to build community consensus around the idea. The ITE +Sponsor should first attempt to ascertain whether the idea is ITE-able. +Posting to the in-toto-dev@googlegroups.com mailing list or opening an issue in +the specification repository footnoteref:[repo] is +the best way to go about this. + +[[discussion]] +==== Discuss the idea with the community + +Vetting an idea publicly before going as far as writing a ITE 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 in-toto 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 in-toto is used. + +Once the sponsor has asked the in-toto community whether an idea has any chance +of acceptance, a "pre-Draft" ITE should be presented to as a pull request to +the ITE repository. The sponsor should needs to notify `@in-toto/ITE-editors` +when they are ready to submit the ITE for <>. + +[[submission]] +==== Creating a ITE Submission + +Following a discussion on jenkinsci-dev@googlegroups.com, +the proposal should be turned into as a ITE submission and submitted +via a GitHub pull request to this repository footnoteref:[repo]. + +IMPORTANT: All submissions must go through pull request, +even those by editors or contributors with "git push" privileges +for the ITE repository footnoteref:[repo]. + +To submit a ITE for <>, the ITE sponsor should: + +. Fork the ITE repository footnoteref:[repo]. +. Clone their forked repository locally. +. Create a new branch called `ite-submission` in their clone. +. Copy the folder `ITE-template/0000` to `ITE/0000`. +. Modify the template ITE in `ITE/0000`. +. Commit and push the changes to their fork + and submit a pull request targeting the `ITE/master` branch. +. Add the following line to the description of the PR to indicate that the ITE + is being submitted for approval as draft: + "Submitted for approval as draft ITE by `@in-toto/ITE-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 ITE 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. + +[[approval]] +==== Approval as Draft ITE + +A ITE editor will check the submission for conformance with ITE structure and +formatting guidelines. Editors may make minor changes to make the submission +meet the requirements for approval as a Draft ITE. If a ITE requires major +changes, editors will add specific feedback and send the submission back to the +sponsor for revision. + +IMPORTANT: "Approval as Draft" is *not* the same as <>. +"Approval as Draft" is an initial conformance and viability check. + +The ITE editors will not unreasonably deny a ITE "Draft" status. +Reasons for denying ITE "Draft" status include: + +* duplication of effort +* being technically unsound +* not providing enough information in all <> + +The <> for this ITE may be consulted during the approval phase, +and is the final arbiter of a submission's approvability as a Draft ITE. + +Once ITE meets requirements for structure and formatting, +the editors will approve the submission as a draft ITE +by following the steps outlined in the +<>. +When they are done, the Draft ITE will have an official ITE number and +the submission PR will have been merged to a matching folder +(for example, +`link:https://github.com/in-toto/ITE/tree/master/ITE/1[ITE/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 +ITE repository footnoteref:[repo] may also approve submissions. +When doing so, that contributor must handle the tasks +that would normally be taken care of by the ITE editors +(see <>). +This includes ensuring the initial version meets the expected standards +for a Draft ITE. + +[[draft]] +==== Refining a Draft ITE + +The version of a ITE that is approved as a Draft ITE +is rarely the same as the final version that is reviewed and hopefully accepted. +A Draft ITE often requires further refinement and expansion +before it is sufficiently complete and represents the consensus of the community. + +Standards Track ITEs consist of two parts, a design document +and a prototype implementation. +The prototype implementation should be co-developed with the ITE, +as ideas that sound good in principle sometimes turn out to be impractical +when subjected to the test of implementation. + +A ITE's sponsor is responsible for collecting community feedback on a ITE +before submitting it for review. +Potential changes to a draft ITE may be discussed further on in-toto-dev@googlegroups.com. +The ITE sponsor may also ask ITE editors for further feedback regarding the + +As updates are necessary, the ITE sponsor and other contributors +should push commits to their fork of the ITE repository footnoteref:[repo], +and submit pull requests targeting the `master` branch. + +[[review]] +==== ITE Review + +Once the sponsor believes a ITE meets at least the minimum criteria to be "<>", +they request the ITE be reviewed for acceptance, usually via +an email to the in-toto-dev@googlegroups.com mailing list. +The ITE <> and their chosen consultants then review the ITE. +If the Reviewer agrees that ITE is ready, they mark the ITE as "<>". +If they do not agree, they leave the ITE as a "Draft", awaiting further revision. +In either case, the reviewer must send a detailed response +to the in-toto-dev@googlegroups.com mailing list explaining their decision. + +ITE review and resolution may also occur on a list other than in-toto-dev@googlegroups.com. +In this case, the "Discussions-To" header in the ITE will identify the +appropriate alternative list where discussion, review and pronouncement on the +ITE will occur. + +[[accepted]] +==== Accepting a ITE + +For a ITE 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 ITEs 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 in-toto unduly. +* have the same license as the component the + proposal is meant to be added to (or Apache 2 licensed by default). + +By marking an ITE as "Accepted" the Reviewer indicates they believe that the +ITE has clear scope, design completeness, community consensus, and (if +applicable) in-progress implementation. Without all of these a ITE cannot be +accepted. For this reason, it is not unusual for ITEs 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 ITE has been accepted, the implementation must continue to progress +and eventually be completed. + +Ideally, all changes to a ITE 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 ITE. + +All changes to an already "Accepted" ITE, 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 <> section. +If there are significant objections or questions around proposed changes, +the ITE Sponsor or Reviewer may choose to return the ITE to a "Draft" status +for more extensive discussion and eventual <>. + +[[final]] +==== Finalizing an ITE +When the implementation is complete and incorporated into the +appropriate "main" code repository, the ITE sponsor will change +the ITE's status changed to "Final". + +Active:: [[active]] +Some Informational and Process ITEs may have a status of "Active" instead of "Final" +These ITEs are ongoing and never meant to be completed per se. E.g. ITE 1 (this ITE). + +[[maintenance]] +==== ITE Maintenance + +Even after a ITE reaches "Final" status, it may need to be updated. + +In general, Standards track ITEs are not modified after they have +reached the Final state. Once a Standards ITE has been completed, Jenkins developer +documentation must become the formal documentation of the expected behavior. + +Informational and Process ITEs 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 ITE being updated. + +Replaced:: [[replaced]] +Final ITEs may eventually also be "Replaced" - superseded by a different ITE - +rendering the original obsolete. +This is intended for Informational ITEs, where version 2 of an API can replace version 1. +When a ITE is marked as replaced, the <> header +must be filled in with a link to the new ITE. + +==== Other ITE Outcomes + +Not all ITEs will be accepted and finalized. + +Rejected:: [[rejected]] +A ITE <> may choose to reject a ITE. +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 ITE is a very strong statement. +If the reviewer believes the ITE might eventually be accepted with sufficient modification, +the reviewer will not reject the ITE. +If a reviewer is confident ITE will never be accepted, +they should inform the ITE sponsor as soon as possible to prevent wasted effort. +On the other hand, even an <> ITE may ultimately be rejected +at some point before it reaches "<>" 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 ITE to Draft status, but this is at the discretion of the reviewer. + +Withdrawn:: [[withdrawn]] +A ITE <> may choose to withdraw a ITE. +Similar to "Rejected", "Withdrawn" means that the ITE sponsor +themselves has decided that the ITE is actually a bad idea, +or agrees that a competing proposal is a better alternative. + +Deferred:: [[deferred]] +A ITE can also be assigned a status of "Deferred". The ITE sponsor or an +editor can assign the ITE this status when no progress is being made +on the ITE. Once a ITE is deferred, a ITE editor can re-assign it +to draft status. + +==== Updating ITE Status and Resolution + +Whenever a ITE status changes, the "Status" field in the ITE document must be +updated. + +The possible paths of a ITE's status are as shown in Figure 1: + +.ITE Workflow +image::workflow.png[ITE Workflow] + +When a ITE is Accepted, Rejected or Withdrawn, +a "<>" section must be added to the ITE Header +with a link to the relevant post in the in-toto-dev@googlegroups.com mailing list archives or the GitHub issue tracker. + +==== Resolving Disputes + +Except for decisions by a ITE's <>, +the ITE process is run by +link:https://en.wikipedia.org/wiki/Consensus_decision-making[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 ITE, +contributors may request that the <> intervene. +The reviewer will consider the matter, and render their decision, +including describing what actions will be taken and documenting their reasoning. + +=== ITE Guidelines + +==== Required Sections + +All ITEs MUST have the following parts to be "approved as Draft": + +. **Metadata** - table containing the <> about the ITE, + including the ITE 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 ITE + 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 ITE solves. + A ITE submission without sufficient discussion of its motivation + will not be approved as a ITE 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 ITEs must include a section describing + any incompatibilities and their severity. + The ITE must explain how it proposes to deal with these incompatibilities. + If there are no backwards compatibility concerns, the section must say that. +. **Security** - All ITEs 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 ITE interacts with existing permissions, authentication, authorization, etc. + If the ITE has no impact on security, the section must say that. +. **Infrastructure Requirements** - + All ITEs must include a section describing their impact on + the in-toto project infrastructure and its supply chain, + including additions or changes, interactions with exiting components, + potential instabilities, service-level agreements, + and assigning responsibility for continuing maintenance. + Each ITE 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 ITE has no impact on infrastructure, the section must say that. +. **Testing** - + All ITEs which include code changes must include a section summarizing how the + changes will be tested. The ITE 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 ITE + has no testing needs, the section must say that. +. **Prototype Implementation** -- + If a ITE 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 ITE to be approved as <>. + The prototype implementation must be sufficient to convey the viability of the design + for a ITE to be <>. + 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. + ITEs which will not include code changes may omit this section. +. **References** -- When moving a ITE 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 ITE + should self-document the process in which it was developed. + +WARNING: ITE submissions that do not adequately complete any of the above +sections will not be approved as ITE Drafts. + +The final implementation must include test code and documentation +appropriate for either the Jenkins user or developer documentation. + +==== ITE File Format + +ITEs are UTF-8 encoded text files using the +link:https://asciidoctor.org[AsciiDoc] format. +AsciiDoc allows for rich markup that is still quite easy to read, +but can also be used to render good-looking and functional HTML. + +[[metadata]] +==== ITE Header Preamble + +===== Required Metadata + +All ITEs MUST begin with an AsciiDoc table containing metadata relevant to the +ITE: + +[source,asciidoc] +---- +.Metadata +[cols="2"] +|=== +| ITE +| 1 + +| Title +| in-toto Enhancement Format + +| Sponsor +| link:https://github.com/santiagotorres[Santiago Torres-Arias] + +| Status +| Draft :speech_balloon: + +| Type +| Process + +| Created +| 2018-10-04 +|=== +---- + + +. **ITE** -- ITE number, given by the ITE editors. Use `0000` until one is assigned. +. **Title** -- Brief title explaining the proposal in fewer than 50 characters +. **Sponsor** -- <> of the ITE, in essence, the individual + responsible for seeing the ITE through the process. +. **Status** -- Draft :speech_balloon:, Deferred :hourglass:, Accepted :ok_hand:, + Rejected :no_entry:, Withdrawn :hand:, Final :lock:, Replaced :dagger:, Active :smile:. +. **Type** -- Describes the type of ITE: Standards, Informational, Process +. **Created** -- Date (`%Y-%m-%d`) when the document was first created. + +===== Additional Header Rows + +Issue:: [[header-issue]] +An **issue identifier** row is available to specify a linked placeholder for an +issue in github, if any. + +Discussions-To:: [[header-discussions-to]] +For a ITE where final pronouncement will be made on a list other than +in-toto-dev@googlegroups.com or the github issue tracker, 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 ITE is being +discussed prior to submission for pronouncement. + +Requires:: [[header-requires]] +ITEs may have a **Requires** row, indicating the ITE numbers that this +ITE depends on. + +Superseded-By:: [[header-superseded-by]] +ITEs may also have a **Superseded-By** row indicating that a ITE has been +rendered obsolete by a later document; the value is the number of the ITE that +replaces the current document. The newer ITE must have a **Replaces** row +containing the number of the ITE that it rendered obsolete. + +Resolution:: [[header-resolution]] +A **Resolution** section will be added to ITEs 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. + + +==== Auxiliary Files + +ITEs may include auxiliary files such as diagrams. Such files must be +named appropriately, with lowercase letters and no spaces, and be included in +the directory with the `README.adoc` describing the ITE. + +=== Reporting ITE Bugs, or Submitting ITE Updates + +The process for reporting a bug or submitting a ITE update depends on several factors, +such as the maturity of the ITE, the preferences of the ITE sponsor, and the nature +of the comments. For the early draft stages of the ITE, it's probably best to +send comments and changes directly to the ITE sponsor. For more mature, or +finished ITEs consider submitting corrections to the ITE repository +footnoteref:[repo] or the in-toto issue tracker +footnoteref:[issues, https://github.com/in-toto/ITE/issues]. If the ITE sponsor is an +in-toto developer, assign the bug/patch to them, otherwise assign it to an ITE +editor. + +When in doubt about where to send changes, please check first with the ITE +sponsor and/or a ITE editor. + + +Even ITE sponsors with git push privileges for the ITE 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. + +[[transferring]] +=== Transferring ITE Sponsorship + +It occasionally becomes necessary to transfer sponsorship of ITEs to a +new sponsor. In general, it is preferable to retain the original sponsor as +a co-sponsor of the transferred ITE, 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 ITE 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 ITE. One aim of the ITE process is to try to build +consensus around a ITE, but if that's not possible, a sponsor can always +submit a competing ITE. + +Ownership of a ITE may also be assumed via pull request. +Fork the ITE repository, footnoteref:[repo] 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 ITE editors via +in-toto-dev@googlegroups.com. If the original sponsor doesn't respond to email in a timely +manner, the ITE editors will make a unilateral decision (it's not like such +decisions can't be reversed :)). + +[[editor-responsibilities]] +=== ITE Editor Responsibilities & Workflow + +A ITE editor must subscribe to the in-toto-dev@googlegroups.com list and must +watch the ITE repository footnoteref:[repo]. Most correspondence regarding ITE +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). + +==== Conformance check + +For each new ITE submission, an editor will: + +* Read the ITE 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 ITE 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. + +==== Request Changes + +If the ITE isn't ready, an editor will send it back to the sponsor for +revision with specific instructions. + +==== Approve as Draft + +Once the ITE is ready for the repository, a ITE editor will: + +. Assign a ITE number (almost always just the next available number, but + may also be a special/joke number, like 666 or 3141). +. Update the folder number to match the ITE number +. Update the ITE number in the document. +. Update the ITE status using the to draft. +. Commit all changes and push them to the branch in the PR +. "Squash and merge" the PR into the `master` branch. + +==== Permission group membership + +Editors add and remove Sponsors from the appropriate permission groups on the +ITE repository. When a ITE includes a new Sponsor, an editor will add that +person to the "ITE Sponsors" or GitHub group respectively. When someone is no +longer an active Sponsor, a ITE 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. + +== Motivation + +in-toto 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). Sometimes, decisions were made and not +properly documented, which resulted in additional overhead and mind-reading +efforts to dig long-established rationales. + +Design documents extending back into the history of in-toto 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, design decisions and already-explored-paths within the in-toto +framework. + +The in-toto Enhancement aims to address both of these major issues by +providing an understood process for making sizable, but understandable, +enhancements to in-toto. + +=== Benefits to existing developers + +ITE provides a systematic approach for vetting and developing new proposals and +ideas for in-toto. By encouraging "everybody to follow the rules" it will be +easier for existing developers to get their ideas and changes into in-toto +without finding themselves mired in unspoken cultural norms within the project. + +=== Benefits to future developers + +By providing clear, understandable, and bite-sized design documents which would +explain various subsections of in-toto. ITEs also make it clearer how an +ambitious new developer to the in-toto project can propose, and make progress +upon, a new idea they have for in-toto. + +Overall, less chaos and more productivity is the rationale for ITE. + +== Reasoning + +=== Based on Python PEP, TAPS and JEP + +The process ITE is modeled after the python, TUF and Jenkins communities, who +have successfully navigated several large-scale reworkings of their codebases, +specifications and processes over the past decade. This includes most notably +the multi-year project of Python 3 (formerly Python 3000) and key format +changes after security audits, as it is in the case of TUF. + +Their Python Enhancement Proposals are largely consensus driven, which is +_mostly_ how work is done presently in the in-toto project, making the PEP +model relatively straightforward to graft onto our existing, processes for +making proposals and deciding upon changes. + +The TUF Augmentation Proposal model is a closer relative to ITE's due that +in-toto and TUF are sister projects. Given the closeness of the communities and +their overlapping developer base, trying to maintain similarities with both +processes is paramount. + +Finally, the Jenkins Enhancement Proposals were the main inspiration of this +document, as JEP 01 was preceived as clearer, more thorough and less ambiguous +than their Python and TUF counterparts. + +=== Differences from Jenkins's JEP + +The Jenkin's JEP proposes a BDFL figure as the ultimate source conflict +resolution. Due to the horizontal nature of in-toto, this aspect of JEP 01 was +ommited. + +=== Differences from Python PEP + +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. + +=== Differences from TUF's TAPs + +The TAP document is closer to a PEP than ITEs are, for ITE's adopted the +organizational structure of JEPs. Furthermore, ITE's adopted asciidoc rather +than markdown, as its syntax has less derivate dialects (e.g., github flavored) +than markdown does. Furtermore, the repository structure of JEP was adopted, as +it allows for the addition of self-hosted diagrams and supporting documents. + +=== Asciidoc style and linter + +There are a number of possible asciidoc style guidelines. +For example, there are a number of reasons to use +link:http://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[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 ITE in that process, +we decided to consider asciidoc style and formatting guidelines in a later ITE. + +== Backwards Compatibility + +There are no backwards compatibility concerns related to this proposal. + +== Security + +There are no security risks related to this proposal. + +== Infrastructure Requirements + +There are no new infrastructure requirements related to this proposal. +This ITE leverages existing infrastructure. + +== References + +=== Related Processes + +* link:https://www.python.org/dev/peps/[Python Enhancement Proposals] +* link:https://github.com/theupdateframework/TAP[TUF Augmentation Proposals] +* link:https://github.com/jenkins-infra/iep[Infrastructure Enhancement Proposal] +* link:https://github.com/jenkinsci/jep[Jenkins Enhancement Proposal] +* link:http://www.ietf.org/rfc.html[IETF RFC] diff --git a/ITE/1/workflow.png b/ITE/1/workflow.png new file mode 100644 index 0000000000000000000000000000000000000000..51eb2b25826c3f97b38a4fa17425a86d27c0d962 GIT binary patch literal 20813 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 literal 0 HcmV?d00001 From bdf64cb86b7e28d737bb372d972cd9f040cd996b Mon Sep 17 00:00:00 2001 From: Justin Cappos Date: Thu, 4 Oct 2018 22:36:23 -0400 Subject: [PATCH 2/9] Typo / spelling fixes... --- ITE/1/README.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index 3c10471..7d3e98c 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -91,7 +91,7 @@ There are three kinds of ITE: recommendation, so users and implementers are free to ignore Informational ITEs or follow their advice. An example of an informational ITE would be the recommendations for integrating in-toto and TUF. -. A **Process** ITE describes a process surrounding the in-toto proejct, or +. A **Process** ITE describes a process surrounding the in-toto project, or proposes a change to (or an event in) a process. Process ITEs are like Standards Track ITEs but apply to areas other than the in-toto specification itself. They may propose an implementation, but not for what would be @@ -264,7 +264,7 @@ If in doubt, sponsors should split their ITE into several well-focused ones. [NOTE] ==== Enhancements or patches which have a smaller impact often don’t need an ITE. -These can be handled via the regular in-tot development workflow with a GitHub +These can be handled via the regular in-toto development workflow with a GitHub issue and/or pull request to the appropriate repository. An ITE may still have an accompanying GitHub issue as a placeholder. This @@ -847,9 +847,9 @@ Overall, less chaos and more productivity is the rationale for ITE. == Reasoning -=== Based on Python PEP, TAPS and JEP +=== Based on Python PEP, TAPS, and JEP -The process ITE is modeled after the python, TUF and Jenkins communities, who +The process ITE is modeled after the python, TUF, and Jenkins communities, who have successfully navigated several large-scale reworkings of their codebases, specifications and processes over the past decade. This includes most notably the multi-year project of Python 3 (formerly Python 3000) and key format @@ -866,14 +866,14 @@ their overlapping developer base, trying to maintain similarities with both processes is paramount. Finally, the Jenkins Enhancement Proposals were the main inspiration of this -document, as JEP 01 was preceived as clearer, more thorough and less ambiguous +document, as JEP 01 was perceived as clearer, more thorough and less ambiguous than their Python and TUF counterparts. === Differences from Jenkins's JEP The Jenkin's JEP proposes a BDFL figure as the ultimate source conflict resolution. Due to the horizontal nature of in-toto, this aspect of JEP 01 was -ommited. +omitted. === Differences from Python PEP From f343bd230d11ec3ce6904f9fe65f6ca3b1f52c52 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Mon, 8 Oct 2018 09:45:03 +0200 Subject: [PATCH 3/9] Replace "a ITE" with "an ITE" --- ITE/1/README.adoc | 110 +++++++++++++++++++++++----------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index 7d3e98c..56e4e45 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -63,7 +63,7 @@ generally ensuring the ITE meets the style, format, and quality guidelines described below. An ITE may also have any number of <> who help write, implement, discuss, or offer feedback about the ITE. One contributor might do only one or any combination of these things -during any part of the life of a ITE. +during any part of the life of an ITE. Because the ITEs are maintained as text files in a versioned repository, their revision history is the historical record of the @@ -118,11 +118,11 @@ requests. Editors are members of a GitHub group called `ITE-editors`. ==== Contributor -A ITE may have any number of `Contributors` who help write, implement, discuss, +An ITE may have any number of `Contributors` who help write, implement, discuss, or offer feedback about that ITE. One contributor might do only one or any -combination of these of these things during any part of the life of a ITE. +combination of these of these things during any part of the life of an ITE. While we invite contributions by companies or other organizations, contributors -listed in a ITE need to be specific people. +listed in an ITE need to be specific people. ==== Sponsor @@ -138,18 +138,18 @@ lifecycle. Their responsibilities include: * Maintaining the ITE after it is finalized * Setting and communicating the schedule as needed -The Sponsor of a ITE may or may not do any of the tasks other contributors do. +The Sponsor of an ITE may or may not do any of the tasks other contributors do. For example, one sponsor might write large portions of one ITE, while another sponsor might leave the writing to other contributors. -Anyone may be Sponsor for a ITE, though it should be someone familiar enough +Anyone may be Sponsor for an ITE, though it should be someone familiar enough with in-toto, the in-toto project, and the ITE workflow to effectively guide the ITE to completion. -A ITE may have more than one Sponsor, especially after it has been finalized +An ITE 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 ITE Sponsor", "a sponsor") when referring the one or more people -in the role of "Sponsor" of a ITE. +in the role of "Sponsor" of an ITE. Sponsors have committer/write access on the ITE repository, but should only approve and merge pull requests for ITEs to which they are assigned. @@ -157,7 +157,7 @@ only approve and merge pull requests for ITEs to which they are assigned. ==== Reviewer The ITE Reviewer is the contributor who will make the final decision whether to -accept a ITE. In all cases where this document refers to the `Reviewer`, it +accept an ITE. In all cases where this document refers to the `Reviewer`, it means "an editor who will review this ITE." [[requirement-levels]] @@ -206,7 +206,7 @@ look at how ITE might go. and a minimal prototype implementation sufficient to convey the viability of the design. She submits the ITE to the <> for <>. - One of the editors checks the submission and determines it is ready to considered as a ITE. + One of the editors checks the submission and determines it is ready to considered as an ITE. They "approve" the submission, assigning the ITE a number, and the submission becomes a "<>" ITE. @@ -249,7 +249,7 @@ it. IMPORTANT: The above is only a high-level overview of the ITE workflow. The full and complete description of the ITE workflow is provided below. -Read the full description below before starting a ITE. +Read the full description below before starting an ITE. [[start]] ==== Start with an idea for in-toto @@ -288,7 +288,7 @@ the best way to go about this. [[discussion]] ==== Discuss the idea with the community -Vetting an idea publicly before going as far as writing a ITE is meant +Vetting an idea publicly before going as far as writing an ITE 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 in-toto community first if an idea is original @@ -305,17 +305,17 @@ the ITE repository. The sponsor should needs to notify `@in-toto/ITE-editors` when they are ready to submit the ITE for <>. [[submission]] -==== Creating a ITE Submission +==== Creating an ITE Submission Following a discussion on jenkinsci-dev@googlegroups.com, -the proposal should be turned into as a ITE submission and submitted +the proposal should be turned into as an ITE submission and submitted via a GitHub pull request to this repository footnoteref:[repo]. IMPORTANT: All submissions must go through pull request, even those by editors or contributors with "git push" privileges for the ITE repository footnoteref:[repo]. -To submit a ITE for <>, the ITE sponsor should: +To submit an ITE for <>, the ITE sponsor should: . Fork the ITE repository footnoteref:[repo]. . Clone their forked repository locally. @@ -338,16 +338,16 @@ with a comment asking for approval as draft. [[approval]] ==== Approval as Draft ITE -A ITE editor will check the submission for conformance with ITE structure and +An ITE editor will check the submission for conformance with ITE structure and formatting guidelines. Editors may make minor changes to make the submission -meet the requirements for approval as a Draft ITE. If a ITE requires major +meet the requirements for approval as a Draft ITE. If an ITE requires major changes, editors will add specific feedback and send the submission back to the sponsor for revision. IMPORTANT: "Approval as Draft" is *not* the same as <>. "Approval as Draft" is an initial conformance and viability check. -The ITE editors will not unreasonably deny a ITE "Draft" status. +The ITE editors will not unreasonably deny an ITE "Draft" status. Reasons for denying ITE "Draft" status include: * duplication of effort @@ -379,7 +379,7 @@ for a Draft ITE. [[draft]] ==== Refining a Draft ITE -The version of a ITE that is approved as a Draft ITE +The version of an ITE that is approved as a Draft ITE is rarely the same as the final version that is reviewed and hopefully accepted. A Draft ITE often requires further refinement and expansion before it is sufficiently complete and represents the consensus of the community. @@ -390,7 +390,7 @@ The prototype implementation should be co-developed with the ITE, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation. -A ITE's sponsor is responsible for collecting community feedback on a ITE +An ITE's sponsor is responsible for collecting community feedback on an ITE before submitting it for review. Potential changes to a draft ITE may be discussed further on in-toto-dev@googlegroups.com. The ITE sponsor may also ask ITE editors for further feedback regarding the @@ -402,7 +402,7 @@ and submit pull requests targeting the `master` branch. [[review]] ==== ITE Review -Once the sponsor believes a ITE meets at least the minimum criteria to be "<>", +Once the sponsor believes an ITE meets at least the minimum criteria to be "<>", they request the ITE be reviewed for acceptance, usually via an email to the in-toto-dev@googlegroups.com mailing list. The ITE <> and their chosen consultants then review the ITE. @@ -417,9 +417,9 @@ appropriate alternative list where discussion, review and pronouncement on the ITE will occur. [[accepted]] -==== Accepting a ITE +==== Accepting an ITE -For a ITE to be "Accepted" it must meet certain minimum criteria. +For an ITE to be "Accepted" it must meet certain minimum criteria. It must: * provide a net improvement. @@ -439,16 +439,16 @@ It must: By marking an ITE as "Accepted" the Reviewer indicates they believe that the ITE has clear scope, design completeness, community consensus, and (if -applicable) in-progress implementation. Without all of these a ITE cannot be +applicable) in-progress implementation. Without all of these an ITE cannot be accepted. For this reason, it is not unusual for ITEs 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 ITE has been accepted, the implementation must continue to progress +Once an ITE has been accepted, the implementation must continue to progress and eventually be completed. -Ideally, all changes to a ITE should be completed before it is "Accepted", +Ideally, all changes to an ITE 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 ITE. @@ -476,7 +476,7 @@ These ITEs are ongoing and never meant to be completed per se. E.g. ITE 1 (this [[maintenance]] ==== ITE Maintenance -Even after a ITE reaches "Final" status, it may need to be updated. +Even after an ITE reaches "Final" status, it may need to be updated. In general, Standards track ITEs are not modified after they have reached the Final state. Once a Standards ITE has been completed, Jenkins developer @@ -490,7 +490,7 @@ Replaced:: [[replaced]] Final ITEs may eventually also be "Replaced" - superseded by a different ITE - rendering the original obsolete. This is intended for Informational ITEs, where version 2 of an API can replace version 1. -When a ITE is marked as replaced, the <> header +When an ITE is marked as replaced, the <> header must be filled in with a link to the new ITE. ==== Other ITE Outcomes @@ -498,12 +498,12 @@ must be filled in with a link to the new ITE. Not all ITEs will be accepted and finalized. Rejected:: [[rejected]] -A ITE <> may choose to reject a ITE. +An ITE <> may choose to reject an ITE. 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 ITE is a very strong statement. +Rejecting an ITE is a very strong statement. If the reviewer believes the ITE might eventually be accepted with sufficient modification, the reviewer will not reject the ITE. If a reviewer is confident ITE will never be accepted, @@ -516,40 +516,40 @@ Upon the request of the sponsor, the reviewer may choose to return a Rejected ITE to Draft status, but this is at the discretion of the reviewer. Withdrawn:: [[withdrawn]] -A ITE <> may choose to withdraw a ITE. +An ITE <> may choose to withdraw an ITE. Similar to "Rejected", "Withdrawn" means that the ITE sponsor themselves has decided that the ITE is actually a bad idea, or agrees that a competing proposal is a better alternative. Deferred:: [[deferred]] -A ITE can also be assigned a status of "Deferred". The ITE sponsor or an +An ITE can also be assigned a status of "Deferred". The ITE sponsor or an editor can assign the ITE this status when no progress is being made -on the ITE. Once a ITE is deferred, a ITE editor can re-assign it +on the ITE. Once an ITE is deferred, an ITE editor can re-assign it to draft status. ==== Updating ITE Status and Resolution -Whenever a ITE status changes, the "Status" field in the ITE document must be +Whenever an ITE status changes, the "Status" field in the ITE document must be updated. -The possible paths of a ITE's status are as shown in Figure 1: +The possible paths of an ITE's status are as shown in Figure 1: .ITE Workflow image::workflow.png[ITE Workflow] -When a ITE is Accepted, Rejected or Withdrawn, +When an ITE is Accepted, Rejected or Withdrawn, a "<>" section must be added to the ITE Header with a link to the relevant post in the in-toto-dev@googlegroups.com mailing list archives or the GitHub issue tracker. ==== Resolving Disputes -Except for decisions by a ITE's <>, +Except for decisions by an ITE's <>, the ITE process is run by link:https://en.wikipedia.org/wiki/Consensus_decision-making[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 ITE, +If consensus cannot be achieved on an ITE, contributors may request that the <> intervene. The reviewer will consider the matter, and render their decision, including describing what actions will be taken and documenting their reasoning. @@ -573,8 +573,8 @@ All ITEs MUST have the following parts to be "approved as Draft": 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 ITE solves. - A ITE submission without sufficient discussion of its motivation - will not be approved as a ITE Draft. + An ITE submission without sufficient discussion of its motivation + will not be approved as an ITE 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. @@ -608,17 +608,17 @@ during discussion. implementation—but it should set out expectations for testability. If the ITE has no testing needs, the section must say that. . **Prototype Implementation** -- - If a ITE will include code changes, + If an ITE 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 ITE to be approved as <>. + The prototype implementation must be present for an ITE to be approved as <>. The prototype implementation must be sufficient to convey the viability of the design - for a ITE to be <>. + for an ITE to be <>. 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. ITEs which will not include code changes may omit this section. -. **References** -- When moving a ITE from a Draft to "Accepted" or "Final" state, +. **References** -- When moving an ITE 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 ITE should self-document the process in which it was developed. @@ -686,7 +686,7 @@ An **issue identifier** row is available to specify a linked placeholder for an issue in github, if any. Discussions-To:: [[header-discussions-to]] -For a ITE where final pronouncement will be made on a list other than +For an ITE where final pronouncement will be made on a list other than in-toto-dev@googlegroups.com or the github issue tracker, 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 ITE is being @@ -697,7 +697,7 @@ ITEs may have a **Requires** row, indicating the ITE numbers that this ITE depends on. Superseded-By:: [[header-superseded-by]] -ITEs may also have a **Superseded-By** row indicating that a ITE has been +ITEs may also have a **Superseded-By** row indicating that an ITE has been rendered obsolete by a later document; the value is the number of the ITE that replaces the current document. The newer ITE must have a **Replaces** row containing the number of the ITE that it rendered obsolete. @@ -717,7 +717,7 @@ the directory with the `README.adoc` describing the ITE. === Reporting ITE Bugs, or Submitting ITE Updates -The process for reporting a bug or submitting a ITE update depends on several factors, +The process for reporting a bug or submitting an ITE update depends on several factors, such as the maturity of the ITE, the preferences of the ITE sponsor, and the nature of the comments. For the early draft stages of the ITE, it's probably best to send comments and changes directly to the ITE sponsor. For more mature, or @@ -728,7 +728,7 @@ in-toto developer, assign the bug/patch to them, otherwise assign it to an ITE editor. When in doubt about where to send changes, please check first with the ITE -sponsor and/or a ITE editor. +sponsor and/or an ITE editor. Even ITE sponsors with git push privileges for the ITE repository should submit @@ -748,10 +748,10 @@ following through with the ITE 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 ITE. One aim of the ITE process is to try to build -consensus around a ITE, but if that's not possible, a sponsor can always +consensus around an ITE, but if that's not possible, a sponsor can always submit a competing ITE. -Ownership of a ITE may also be assumed via pull request. +Ownership of an ITE may also be assumed via pull request. Fork the ITE repository, footnoteref:[repo] 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 ITE editors via @@ -762,7 +762,7 @@ decisions can't be reversed :)). [[editor-responsibilities]] === ITE Editor Responsibilities & Workflow -A ITE editor must subscribe to the in-toto-dev@googlegroups.com list and must +An ITE editor must subscribe to the in-toto-dev@googlegroups.com list and must watch the ITE repository footnoteref:[repo]. Most correspondence regarding ITE administration can be handled through GitHub issues and pull requests. @@ -791,9 +791,9 @@ revision with specific instructions. ==== Approve as Draft -Once the ITE is ready for the repository, a ITE editor will: +Once the ITE is ready for the repository, an ITE editor will: -. Assign a ITE number (almost always just the next available number, but +. Assign an ITE number (almost always just the next available number, but may also be a special/joke number, like 666 or 3141). . Update the folder number to match the ITE number . Update the ITE number in the document. @@ -804,9 +804,9 @@ Once the ITE is ready for the repository, a ITE editor will: ==== Permission group membership Editors add and remove Sponsors from the appropriate permission groups on the -ITE repository. When a ITE includes a new Sponsor, an editor will add that +ITE repository. When an ITE includes a new Sponsor, an editor will add that person to the "ITE Sponsors" or GitHub group respectively. When someone is no -longer an active Sponsor, a ITE editor will remove them from the permission +longer an active Sponsor, an ITE 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. From 91d48a67c77a15cf5096163910c5dd648a63c7f6 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Mon, 8 Oct 2018 12:21:25 +0200 Subject: [PATCH 4/9] Replace jenkins with in-toto where appropriate This document is based on the jenkins enhancement proposal (JEP) and did not replace all occurrences of jenkins that should be in-toto. This commit fixes this addressing @trishankatdatadog's review comments: https://github.com/in-toto/ITE/pull/1#pullrequestreview-162120272 --- ITE/1/README.adoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index 56e4e45..44b11d9 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -290,7 +290,7 @@ the best way to go about this. Vetting an idea publicly before going as far as writing an ITE is meant to save the potential sponsor time. Many ideas have been brought -forward for changing Jenkins that have been rejected for various +forward for changing in-toto that have been rejected for various reasons. Asking the in-toto 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 @@ -307,7 +307,7 @@ when they are ready to submit the ITE for <>. [[submission]] ==== Creating an ITE Submission -Following a discussion on jenkinsci-dev@googlegroups.com, +Following a discussion on in-toto-dev@googlegroups, the proposal should be turned into as an ITE submission and submitted via a GitHub pull request to this repository footnoteref:[repo]. @@ -479,7 +479,7 @@ These ITEs are ongoing and never meant to be completed per se. E.g. ITE 1 (this Even after an ITE reaches "Final" status, it may need to be updated. In general, Standards track ITEs are not modified after they have -reached the Final state. Once a Standards ITE has been completed, Jenkins developer +reached the Final state. Once a Standards ITE has been completed, in-toto developer documentation must become the formal documentation of the expected behavior. Informational and Process ITEs may be updated over time to reflect changes @@ -567,10 +567,10 @@ All ITEs MUST have the following parts to be "approved as Draft": 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 + sufficiently detailed to allow new or existing in-toto developers to reasonably understand the scope/impact of an implementation. . **Motivation** - A clear description of the motivation is critical for any ITE - that wants to change Jenkins or the Jenkins project. + that wants to change in-toto or the in-toto project. The motivation section should clearly explain why the existing code base or process is inadequate to address the problem that the ITE solves. An ITE submission without sufficient discussion of its motivation @@ -627,7 +627,7 @@ WARNING: ITE submissions that do not adequately complete any of the above sections will not be approved as ITE Drafts. The final implementation must include test code and documentation -appropriate for either the Jenkins user or developer documentation. +appropriate for either the in-toto user or developer documentation. ==== ITE File Format @@ -706,7 +706,7 @@ Resolution:: [[header-resolution]] A **Resolution** section will be added to ITEs 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. +in-toto-dev@googlegroups.com mailing list archives. ==== Auxiliary Files From c27879cc9ffb562fdcc18f6ea7397e6021c6b527 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Mon, 8 Oct 2018 12:25:24 +0200 Subject: [PATCH 5/9] Fix minor typos/spelling/punctuation - Remove stray words. - Add missing words. - Fix some commas, periods, apostrophes. --- ITE/1/README.adoc | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index 44b11d9..c252942 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -38,7 +38,7 @@ endif::[] == Abstract An in-toto Enhancement (ITE) is a design document that describes a new feature -or aspect of the in-toto framework, a setup of its supply chain or an, +or aspect of the in-toto framework, a setup of its supply chain, or an organizational aspect of the in-toto project. This ITE describes the structure of ITE documents and details the process by which ITEs are created, submitted, reviewed, finalized, and maintained. @@ -50,7 +50,7 @@ reviewed, finalized, and maintained. ITE stands for in-toto Enhancement. An ITE is a design document that describes a new feature or aspect of the in-toto framework, the in-toto supply chain, or -the process within in-toto project. An ITE provides a concise technical +the process within the in-toto project. An ITE provides a concise technical specification of the feature, describes the motivation for the change, and discusses the rationale behind the design. @@ -84,10 +84,10 @@ There are three kinds of ITE: for the in-toto specification. It may also describe an interoperability or backwards-compatibility standard which will be supported for the feature in current versions of in-toto, moving forward. -. An **Informational** ITE describes an in-totodesign issue, or +. An **Informational** ITE describes an in-toto design issue, or provides general guidelines or information to the in-toto community, but does not propose a new feature. Informational ITEs do not - necessarily represent a in-toto community consensus or + necessarily represent an in-toto community consensus or recommendation, so users and implementers are free to ignore Informational ITEs or follow their advice. An example of an informational ITE would be the recommendations for integrating in-toto and TUF. @@ -120,7 +120,7 @@ requests. Editors are members of a GitHub group called `ITE-editors`. An ITE may have any number of `Contributors` who help write, implement, discuss, or offer feedback about that ITE. One contributor might do only one or any -combination of these of these things during any part of the life of an ITE. +combination of these things during any part of the life of an ITE. While we invite contributions by companies or other organizations, contributors listed in an ITE need to be specific people. @@ -163,7 +163,7 @@ means "an editor who will review this ITE." [[requirement-levels]] ==== Must/Should/May -ITE documents _must_ follow link:https://tools.ietf.org/html/rfc2119[RFC 2119] +ITE documents _must_ follow link:https://tools.ietf.org/html/rfc2119[RFC 2119], which defines key words to "indicate requirement levels". These are listed below: @@ -193,7 +193,7 @@ the reasons behind that choice SHOULD be documented. Before delving into the details of the ITE workflow, let's take a high-level look at how ITE might go. -. **<>** - Andrea has an idea for new feature and emails it in-toto-dev@googlegroups.com. +. **<>** - Andrea has an idea for new feature and emails it to in-toto-dev@googlegroups.com. She discusses the idea with the group, determining that the idea is worth pursuing. She chooses to be the "<>" for this potential ITE. She <> from the community, adjusts her design as needed, @@ -206,7 +206,7 @@ look at how ITE might go. and a minimal prototype implementation sufficient to convey the viability of the design. She submits the ITE to the <> for <>. - One of the editors checks the submission and determines it is ready to considered as an ITE. + One of the editors checks the submission and determines it is ready to be considered as an ITE. They "approve" the submission, assigning the ITE a number, and the submission becomes a "<>" ITE. @@ -271,7 +271,7 @@ An ITE may still have an accompanying GitHub issue as a placeholder. This might be useful, for example, if implementation of the ITE is later found to have introduced a bug; being able to link the `regression`-labelled GitHub issue to the placeholder is valuable for tracking purposes. In such a case be sure -to specify a "<>" section. +to specify an "<>" section. ==== @@ -357,7 +357,7 @@ Reasons for denying ITE "Draft" status include: The <> for this ITE may be consulted during the approval phase, and is the final arbiter of a submission's approvability as a Draft ITE. -Once ITE meets requirements for structure and formatting, +Once an ITE meets requirements for structure and formatting, the editors will approve the submission as a draft ITE by following the steps outlined in the <>. @@ -403,7 +403,7 @@ and submit pull requests targeting the `master` branch. ==== ITE Review Once the sponsor believes an ITE meets at least the minimum criteria to be "<>", -they request the ITE be reviewed for acceptance, usually via +they request the ITE to be reviewed for acceptance, usually via an email to the in-toto-dev@googlegroups.com mailing list. The ITE <> and their chosen consultants then review the ITE. If the Reviewer agrees that ITE is ready, they mark the ITE as "<>". @@ -467,10 +467,10 @@ for more extensive discussion and eventual <> ITE may ultimately be rejected at some point before it reaches "<>" status, @@ -595,7 +595,7 @@ during discussion. . **Infrastructure Requirements** - All ITEs must include a section describing their impact on the in-toto project infrastructure and its supply chain, - including additions or changes, interactions with exiting components, + including additions or changes, interactions with existing components, potential instabilities, service-level agreements, and assigning responsibility for continuing maintenance. Each ITE must explain the scope of infrastructure changes with sufficient detail @@ -807,7 +807,7 @@ Editors add and remove Sponsors from the appropriate permission groups on the ITE repository. When an ITE includes a new Sponsor, an editor will add that person to the "ITE Sponsors" or GitHub group respectively. When someone is no longer an active Sponsor, an ITE editor will remove them from the permission -group. Editors will clean up the the permission groups from time to time as +group. Editors will clean up the permission groups from time to time as they see the need or are asked to do so. == Motivation @@ -857,10 +857,10 @@ changes after security audits, as it is in the case of TUF. Their Python Enhancement Proposals are largely consensus driven, which is _mostly_ how work is done presently in the in-toto project, making the PEP -model relatively straightforward to graft onto our existing, processes for +model relatively straightforward to graft onto our existing processes for making proposals and deciding upon changes. -The TUF Augmentation Proposal model is a closer relative to ITE's due that +The TUF Augmentation Proposal model is a closer relative to ITEs due that in-toto and TUF are sister projects. Given the closeness of the communities and their overlapping developer base, trying to maintain similarities with both processes is paramount. @@ -869,9 +869,9 @@ Finally, the Jenkins Enhancement Proposals were the main inspiration of this document, as JEP 01 was perceived as clearer, more thorough and less ambiguous than their Python and TUF counterparts. -=== Differences from Jenkins's JEP +=== Differences from Jenkins' JEP -The Jenkin's JEP proposes a BDFL figure as the ultimate source conflict +The Jenkins' JEP proposes a BDFL figure as the ultimate source of conflict resolution. Due to the horizontal nature of in-toto, this aspect of JEP 01 was omitted. @@ -884,8 +884,8 @@ confusion. === Differences from TUF's TAPs -The TAP document is closer to a PEP than ITEs are, for ITE's adopted the -organizational structure of JEPs. Furthermore, ITE's adopted asciidoc rather +The TAP document is closer to a PEP than ITEs are, for ITEs adopted the +organizational structure of JEPs. Furthermore, ITEs adopted asciidoc rather than markdown, as its syntax has less derivate dialects (e.g., github flavored) than markdown does. Furtermore, the repository structure of JEP was adopted, as it allows for the addition of self-hosted diagrams and supporting documents. From c0158ec61c780ffe8b08be5adf6aaac08746235f Mon Sep 17 00:00:00 2001 From: Santiago Torres Date: Wed, 10 Oct 2018 23:40:23 -0400 Subject: [PATCH 6/9] FIX: addresses comments by Reza and Lukas --- ITE/1/README.adoc | 173 ++++++++++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 84 deletions(-) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index c252942..099cccc 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -89,7 +89,7 @@ There are three kinds of ITE: but does not propose a new feature. Informational ITEs do not necessarily represent an in-toto community consensus or recommendation, so users and implementers are free to ignore - Informational ITEs or follow their advice. An example of an informational ITE + Informational ITEs or follow their advice. An example of an Informational ITE would be the recommendations for integrating in-toto and TUF. . A **Process** ITE describes a process surrounding the in-toto project, or proposes a change to (or an event in) a process. Process ITEs are like @@ -107,14 +107,14 @@ There are three kinds of ITE: ==== Editor -The ITE editors are individuals responsible for managing the administrative +The ITE Editors are individuals responsible for managing the administrative and editorial aspects of the ITE workflow (e.g. assigning ITE numbers and -changing their status). See <> for +changing their status). See <> for details. -ITE editorship is by invitation of the current editors. All of the ITE workflow -can be conducted via the GitHub ITE Repository footnoteref:[repo] and pull -requests. Editors are members of a GitHub group called `ITE-editors`. +ITE editorship is given by invitation of the current Editors. All of the ITE +workflow can be conducted via the GitHub ITE Repository footnoteref:[repo] and +pull requests. Editors are members of a GitHub group called `ITE-editors`. ==== Contributor @@ -124,6 +124,9 @@ combination of these things during any part of the life of an ITE. While we invite contributions by companies or other organizations, contributors listed in an ITE need to be specific people. +Also a Sponsor, a Reviewer, or an Editor of an ITE, is also considered a +Contributor. + ==== Sponsor Each ITE has at least one "Sponsor". @@ -136,19 +139,20 @@ lifecycle. Their responsibilities include: * Coordinating contributors' work * Ensuring the ITE meets the style, format, and quality guidelines * Maintaining the ITE after it is finalized -* Setting and communicating the schedule as needed +* Setting and communicating the schedule for the development of this ITE as + needed The Sponsor of an ITE may or may not do any of the tasks other contributors do. -For example, one sponsor might write large portions of one ITE, while another -sponsor might leave the writing to other contributors. +For example, one Sponsor might write large portions of one ITE, while another +Sponsor might leave the writing to other contributors. -Anyone may be Sponsor for an ITE, though it should be someone familiar enough +Anyone may be a Sponsor for an ITE, though it should be someone familiar enough with in-toto, the in-toto project, and the ITE workflow to effectively guide the ITE to completion. An ITE 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 ITE Sponsor", "a sponsor") when referring the one or more people +singular ("The ITE Sponsor", "a Sponsor") when referring the one or more people in the role of "Sponsor" of an ITE. Sponsors have committer/write access on the ITE repository, but should @@ -158,7 +162,7 @@ only approve and merge pull requests for ITEs to which they are assigned. The ITE Reviewer is the contributor who will make the final decision whether to accept an ITE. In all cases where this document refers to the `Reviewer`, it -means "an editor who will review this ITE." +means "an Editor who will review this ITE." [[requirement-levels]] ==== Must/Should/May @@ -193,7 +197,7 @@ the reasons behind that choice SHOULD be documented. Before delving into the details of the ITE workflow, let's take a high-level look at how ITE might go. -. **<>** - Andrea has an idea for new feature and emails it to in-toto-dev@googlegroups.com. +. **<>** - Andrea has an idea for a new feature and emails it to in-toto-dev@googlegroups.com. She discusses the idea with the group, determining that the idea is worth pursuing. She chooses to be the "<>" for this potential ITE. She <> from the community, adjusts her design as needed, @@ -204,9 +208,9 @@ look at how ITE might go. 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 ITE to the <> for + She submits the ITE to the <> for <>. - One of the editors checks the submission and determines it is ready to be considered as an ITE. + One of the Editors checks the submission and determines it is ready to be considered as an ITE. They "approve" the submission, assigning the ITE a number, and the submission becomes a "<>" ITE. @@ -221,7 +225,7 @@ look at how ITE might go. . **<>** - Kelly reviews the ITE and any related discussions and implementation. Kelly agrees with Andrea that consensus has been reached - regarding the ITE and that the implementation is far enough along to enusure + regarding the ITE and that the implementation is far enough along to ensure that the design is stable and complete. Kelly marks the ITE as an "<>" ITE. @@ -257,9 +261,9 @@ Read the full description below before starting an ITE. The ITE process begins with a new idea for in-toto. A single ITE should contain a single key proposal or new idea. The more focused the ITE, the more successful it tends to be. -The ITE editors reserve the right to reject potential ITEs +The ITE Editors reserve the right to reject potential ITEs if they appear too unfocused or too broad. -If in doubt, sponsors should split their ITE into several well-focused ones. +If in doubt, Sponsors should split their ITE into several well-focused ones. [NOTE] ==== @@ -282,26 +286,26 @@ style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The ITE Sponsor should first attempt to ascertain whether the idea is ITE-able. Posting to the in-toto-dev@googlegroups.com mailing list or opening an issue in -the specification repository footnoteref:[repo] is -the best way to go about this. +the specification repository footnoteref:[docs https://github.com/in-toto/docs] +is the best way to go about this. [[discussion]] ==== Discuss the idea with the community Vetting an idea publicly before going as far as writing an ITE is meant -to save the potential sponsor time. Many ideas have been brought +to save the potential Sponsor time. Many ideas have been brought forward for changing in-toto that have been rejected for various reasons. Asking the in-toto 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 +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 in-toto is used. -Once the sponsor has asked the in-toto community whether an idea has any chance +Once the Sponsor has asked the in-toto community whether an idea has any chance of acceptance, a "pre-Draft" ITE should be presented to as a pull request to -the ITE repository. The sponsor should needs to notify `@in-toto/ITE-editors` +the ITE repository. The Sponsor should notify `@in-toto/ITE-editors` when they are ready to submit the ITE for <>. [[submission]] @@ -312,16 +316,16 @@ the proposal should be turned into as an ITE submission and submitted via a GitHub pull request to this repository footnoteref:[repo]. IMPORTANT: All submissions must go through pull request, -even those by editors or contributors with "git push" privileges +even those by Editors or contributors with "git push" privileges for the ITE repository footnoteref:[repo]. -To submit an ITE for <>, the ITE sponsor should: +To submit an ITE for <>, the ITE Sponsor should: . Fork the ITE repository footnoteref:[repo]. . Clone their forked repository locally. . Create a new branch called `ite-submission` in their clone. . Copy the folder `ITE-template/0000` to `ITE/0000`. -. Modify the template ITE in `ITE/0000`. +. Modify the copy of the template ITE in `ITE/0000`. . Commit and push the changes to their fork and submit a pull request targeting the `ITE/master` branch. . Add the following line to the description of the PR to indicate that the ITE @@ -331,23 +335,23 @@ To submit an ITE for <>, the ITE sponsor should: the line requesting approval should be added as a comment when the ITE is ready. -The sponsor may alter the steps above or do something else entirely +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. [[approval]] ==== Approval as Draft ITE -An ITE editor will check the submission for conformance with ITE structure and +An ITE Editor will check the submission for conformance with ITE structure and formatting guidelines. Editors may make minor changes to make the submission meet the requirements for approval as a Draft ITE. If an ITE requires major -changes, editors will add specific feedback and send the submission back to the -sponsor for revision. +changes, Editors will add specific feedback and send the submission back to the +Sponsor for revision. IMPORTANT: "Approval as Draft" is *not* the same as <>. "Approval as Draft" is an initial conformance and viability check. -The ITE editors will not unreasonably deny an ITE "Draft" status. +The ITE Editors will not unreasonably deny an ITE "Draft" status. Reasons for denying ITE "Draft" status include: * duplication of effort @@ -358,9 +362,9 @@ The <> for this ITE may be consulted during the approval phase, and is the final arbiter of a submission's approvability as a Draft ITE. Once an ITE meets requirements for structure and formatting, -the editors will approve the submission as a draft ITE +the Editors will approve the submission as a draft ITE by following the steps outlined in the -<>. +<>. When they are done, the Draft ITE will have an official ITE number and the submission PR will have been merged to a matching folder (for example, @@ -368,10 +372,10 @@ the submission PR will have been merged to a matching folder 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 +Non-Editor contributors who have "git push" privileges for the ITE repository footnoteref:[repo] may also approve submissions. When doing so, that contributor must handle the tasks -that would normally be taken care of by the ITE editors +that would normally be taken care of by the ITE Editors (see <>). This includes ensuring the initial version meets the expected standards for a Draft ITE. @@ -390,25 +394,26 @@ The prototype implementation should be co-developed with the ITE, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation. -An ITE's sponsor is responsible for collecting community feedback on an ITE +An ITE's Sponsor is responsible for collecting community feedback on an ITE before submitting it for review. Potential changes to a draft ITE may be discussed further on in-toto-dev@googlegroups.com. -The ITE sponsor may also ask ITE editors for further feedback regarding the +The ITE Sponsor may also ask ITE Editors for further feedback regarding the +technical quality of the ITE proposed. -As updates are necessary, the ITE sponsor and other contributors +As updates are necessary, the ITE Sponsor and other contributors should push commits to their fork of the ITE repository footnoteref:[repo], and submit pull requests targeting the `master` branch. [[review]] ==== ITE Review -Once the sponsor believes an ITE meets at least the minimum criteria to be "<>", +Once the Sponsor believes an ITE meets at least the minimum criteria to be "<>", they request the ITE to be reviewed for acceptance, usually via an email to the in-toto-dev@googlegroups.com mailing list. The ITE <> and their chosen consultants then review the ITE. If the Reviewer agrees that ITE is ready, they mark the ITE as "<>". If they do not agree, they leave the ITE as a "Draft", awaiting further revision. -In either case, the reviewer must send a detailed response +In either case, the Reviewer must send a detailed response to the in-toto-dev@googlegroups.com mailing list explaining their decision. ITE review and resolution may also occur on a list other than in-toto-dev@googlegroups.com. @@ -439,7 +444,7 @@ It must: By marking an ITE as "Accepted" the Reviewer indicates they believe that the ITE has clear scope, design completeness, community consensus, and (if -applicable) in-progress implementation. Without all of these an ITE cannot be +applicable) in progress implementation. Without all of these an ITE cannot be accepted. For this reason, it is not unusual for ITEs 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 @@ -466,7 +471,7 @@ for more extensive discussion and eventual <> ITE may ultimately be rejected at some point before it reaches "<>" 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 ITE to Draft status, but this is at the discretion of the reviewer. +Upon the request of the Sponsor, the Reviewer may choose to return a +Rejected ITE to Draft status, but this is at the discretion of the Reviewer. Withdrawn:: [[withdrawn]] An ITE <> may choose to withdraw an ITE. -Similar to "Rejected", "Withdrawn" means that the ITE sponsor +Similar to "Rejected", "Withdrawn" means that the ITE Sponsor themselves has decided that the ITE is actually a bad idea, or agrees that a competing proposal is a better alternative. Deferred:: [[deferred]] -An ITE can also be assigned a status of "Deferred". The ITE sponsor or an -editor can assign the ITE this status when no progress is being made -on the ITE. Once an ITE is deferred, an ITE editor can re-assign it +An ITE can also be assigned a status of "Deferred". The ITE Sponsor or an +Editor can assign the ITE this status when no progress is being made +on the ITE. Once an ITE is deferred, an ITE Editor can re-assign it to draft status. ==== Updating ITE Status and Resolution @@ -550,8 +555,8 @@ 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 an ITE, -contributors may request that the <> intervene. -The reviewer will consider the matter, and render their decision, +contributors may request that the <> intervene. +The Reviewer will consider the matter, and render their decision, including describing what actions will be taken and documenting their reasoning. === ITE Guidelines @@ -562,7 +567,7 @@ All ITEs MUST have the following parts to be "approved as Draft": . **Metadata** - table containing the <> about the ITE, including the ITE number, a short descriptive title, the names, - and optionally the contact info for each sponsor, etc. + 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 @@ -670,7 +675,7 @@ ITE: ---- -. **ITE** -- ITE number, given by the ITE editors. Use `0000` until one is assigned. +. **ITE** -- ITE number, given by the ITE Editors. Use `0000` until one is assigned. . **Title** -- Brief title explaining the proposal in fewer than 50 characters . **Sponsor** -- <> of the ITE, in essence, the individual responsible for seeing the ITE through the process. @@ -718,20 +723,20 @@ the directory with the `README.adoc` describing the ITE. === Reporting ITE Bugs, or Submitting ITE Updates The process for reporting a bug or submitting an ITE update depends on several factors, -such as the maturity of the ITE, the preferences of the ITE sponsor, and the nature +such as the maturity of the ITE, the preferences of the ITE Sponsor, and the nature of the comments. For the early draft stages of the ITE, it's probably best to -send comments and changes directly to the ITE sponsor. For more mature, or +send comments and changes directly to the ITE Sponsor. For more mature, or finished ITEs consider submitting corrections to the ITE repository footnoteref:[repo] or the in-toto issue tracker -footnoteref:[issues, https://github.com/in-toto/ITE/issues]. If the ITE sponsor is an +footnoteref:[issues, https://github.com/in-toto/ITE/issues]. If the ITE Sponsor is an in-toto developer, assign the bug/patch to them, otherwise assign it to an ITE -editor. +Editor. When in doubt about where to send changes, please check first with the ITE -sponsor and/or an ITE editor. +Sponsor and/or an ITE Editor. -Even ITE sponsors with git push privileges for the ITE repository should submit +Even ITE Sponsors with git push privileges for the ITE 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. @@ -740,38 +745,38 @@ and agreed to elsewhere. === Transferring ITE Sponsorship It occasionally becomes necessary to transfer sponsorship of ITEs to a -new sponsor. In general, it is preferable to retain the original sponsor as -a co-sponsor of the transferred ITE, 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 +new Sponsor. In general, it is preferable to retain the original Sponsor as +a co-Sponsor of the transferred ITE, 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 ITE 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 +the internet (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 ITE. One aim of the ITE process is to try to build -consensus around an ITE, but if that's not possible, a sponsor can always +consensus around an ITE, but if that's not possible, a Sponsor can always submit a competing ITE. Ownership of an ITE may also be assumed via pull request. Fork the ITE repository, footnoteref:[repo] 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 ITE editors via -in-toto-dev@googlegroups.com. If the original sponsor doesn't respond to email in a timely -manner, the ITE editors will make a unilateral decision (it's not like such +to take over, addressed to both the original Sponsor and the ITE Editors via +in-toto-dev@googlegroups.com. If the original Sponsor doesn't respond to email in a timely +manner, the ITE Editors will make a unilateral decision (it's not like such decisions can't be reversed :)). -[[editor-responsibilities]] +[[Editor-responsibilities]] === ITE Editor Responsibilities & Workflow -An ITE editor must subscribe to the in-toto-dev@googlegroups.com list and must +An ITE Editor must subscribe to the in-toto-dev@googlegroups.com list and must watch the ITE repository footnoteref:[repo]. Most correspondence regarding ITE administration can be handled through GitHub issues and pull requests. -Aside from the editorial cases outlined below, editors should submit all +Aside from the editorial cases outlined below, Editors should submit all changes as GitHub pull requests (the same as any other contributor). ==== Conformance check -For each new ITE submission, an editor will: +For each new ITE submission, an Editor will: * Read the ITE to check if it is ready, sound, and complete. The ideas must make technical sense, even if they don't seem likely to be @@ -782,16 +787,16 @@ For each new ITE submission, an editor will: * Edit the ITE 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. +the Editor may choose to provide feedback instead. ==== Request Changes -If the ITE isn't ready, an editor will send it back to the sponsor for +If the ITE isn't ready, an Editor will send it back to the Sponsor for revision with specific instructions. ==== Approve as Draft -Once the ITE is ready for the repository, an ITE editor will: +Once the ITE is ready for the repository, an ITE Editor will: . Assign an ITE number (almost always just the next available number, but may also be a special/joke number, like 666 or 3141). @@ -804,9 +809,9 @@ Once the ITE is ready for the repository, an ITE editor will: ==== Permission group membership Editors add and remove Sponsors from the appropriate permission groups on the -ITE repository. When an ITE includes a new Sponsor, an editor will add that +ITE repository. When an ITE includes a new Sponsor, an Editor will add that person to the "ITE Sponsors" or GitHub group respectively. When someone is no -longer an active Sponsor, an ITE editor will remove them from the permission +longer an active Sponsor, an ITE Editor will remove them from the permission group. Editors will clean up the permission groups from time to time as they see the need or are asked to do so. @@ -816,7 +821,7 @@ in-toto 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). Sometimes, decisions were made and not properly documented, which resulted in additional overhead and mind-reading -efforts to dig long-established rationales. +efforts to dig up long-established rationales. Design documents extending back into the history of in-toto are few and far between, as the project grew organically over time. As such, a contributor, From 55d28e8860e4e4696fadcdec07f4d728b448b561 Mon Sep 17 00:00:00 2001 From: Santiago Torres Date: Wed, 10 Oct 2018 23:58:41 -0400 Subject: [PATCH 7/9] ENH: add ITE template --- ITE-template/0000/README.adoc | 95 +++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 ITE-template/0000/README.adoc diff --git a/ITE-template/0000/README.adoc b/ITE-template/0000/README.adoc new file mode 100644 index 0000000..9f0178c --- /dev/null +++ b/ITE-template/0000/README.adoc @@ -0,0 +1,95 @@ += ITE-1: in-toto Enhancement Format +:source-highlighter: pygments +:toc: preamble +:toclevels: 2 +ifdef::env-github[] +:tip-caption: :bulb: +:note-caption: :information_source: +:important-caption: :heavy_exclamation_mark: +:caution-caption: :fire: +:warning-caption: :warning: +endif::[] + +.Metadata +[cols="2"] +|=== +| ITE +| 0000 + +| Title +| in-toto Enhancement template + +| Sponsor +| link:https://github.com/yourusernamehere[John Doe] + +| Status +| Active :smile: + +| Type +| Process + +| Created +| yyyy-mm-dd + +|=== + + +[[abstract]] +== Abstract + +An abstract of approximately 200 words describing the technical issue +addressed. + +[[specification]] +== Specification + +The specification text here. Describe in depth the feature that you may want to +integrate. + +[[motivation]] +== Motivation + +Here, describe the rationale behind the changes you are proposing. + +[[reasoning]] +== Reasoning + +Here, describe why the decisions you made in the specification make sense. + +[[backwards-compatibility]] +== Backwards Compatibility + +Describe how these changes will affect backwards compatibility and how do you +plan on mitigating the effects of these. + +[[security]] +== Security + +Provide a security analisis of these changes including the threat model +considered (and how it differs from the existing threat model for in-toto). +Mention the security impact of adding these changes to in-toto. + +[[infrastructure-requirements]] +== Infrastructure Requirements + +If your changes require additional infrastructure, describe it here. Include +potential costs incurred considering both time and money. + +[[testing]] +== Testing + +If your implementation includes code, include this section describing how your +changes will be tested. + +[[prototype-implementation]] +== Prototype Implementation + +If your ITE includes code changes, provide some links to the prototype +implementation of these changes. + +[[references]] +== References + +=== example references + +* link:http://www.ietf.org/rfc.html[IETF RFC] From c585dd73e3590c39ced47be7758069295edf2ff5 Mon Sep 17 00:00:00 2001 From: Santiago Torres Date: Thu, 18 Oct 2018 12:23:14 -0400 Subject: [PATCH 8/9] FIX: address feedback from Reza, Lukpueh - Add optional replaces header - Clarify sentence in motivation for this ITE - Add the missing testing section --- ITE/1/README.adoc | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index 099cccc..5e2f569 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -701,6 +701,10 @@ Requires:: [[header-requires]] ITEs may have a **Requires** row, indicating the ITE numbers that this ITE depends on. +Replaces:: [[header-replaces]] +An ITE that replaces another ITE must have a **Replaces** row containing the +number of the ITE that it rendered obsolete. + Superseded-By:: [[header-superseded-by]] ITEs may also have a **Superseded-By** row indicating that an ITE has been rendered obsolete by a later document; the value is the number of the ITE that @@ -844,11 +848,12 @@ without finding themselves mired in unspoken cultural norms within the project. === Benefits to future developers By providing clear, understandable, and bite-sized design documents which would -explain various subsections of in-toto. ITEs also make it clearer how an -ambitious new developer to the in-toto project can propose, and make progress -upon, a new idea they have for in-toto. +explain various subsections of in-toto, users and developers follow, support, +and oppose design decisions. ITEs also make it clearer how an ambitious new +developer to the in-toto project can propose, and make progress upon, a new +idea they have for in-toto. -Overall, less chaos and more productivity is the rationale for ITE. +Overall, less chaos and more productivity is the rationale for ITEs. == Reasoning @@ -914,6 +919,10 @@ There are no backwards compatibility concerns related to this proposal. There are no security risks related to this proposal. +== Testing + +There are no testing additions related to this ITE. + == Infrastructure Requirements There are no new infrastructure requirements related to this proposal. From 4a36990c34920c0e43eb3a8f3546eb7d05e4fb84 Mon Sep 17 00:00:00 2001 From: Santiago Torres Date: Mon, 22 Oct 2018 12:50:05 -0400 Subject: [PATCH 9/9] ENH: 01: add scheduling and timeline This adds an expected timeline section to specify what's the expected time to spend on each section of the ITE admission process. --- ITE/1/README.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc index 5e2f569..72f959e 100644 --- a/ITE/1/README.adoc +++ b/ITE/1/README.adoc @@ -634,6 +634,22 @@ sections will not be approved as ITE Drafts. The final implementation must include test code and documentation appropriate for either the in-toto user or developer documentation. +==== ITE scheduling and timelines + +ITE Editors are volunteers, and as such they will try to ensure timely response +to new ITE proposals to the best of their availability. However, a delay of +more than a week to reject or accept a new ITE as draft is to be expected. + +Once an ITE is accepted as a Draft, the Sponsor and the rest of the community +is expected to do continuous progress towards a decision for acceptance. Given +the nature of the process, it is possible that multiple iterations are done +during the discussion period. Due to this there is not a concrete timeline for +a draft to move from draft to accepted status. In contrast, a draft without +activity for a month since the last comment is expected to be moved to deferred +status. Likewise, An ITE SHALL spend no longer than two months in any given +state other than deferred. + + ==== ITE File Format ITEs are UTF-8 encoded text files using the