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] diff --git a/ITE/1/README.adoc b/ITE/1/README.adoc new file mode 100644 index 0000000..72f959e --- /dev/null +++ b/ITE/1/README.adoc @@ -0,0 +1,955 @@ += 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 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. + +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 an 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-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 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. +. 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 + 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 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 + +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 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". + +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 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. + +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 +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. + +==== Reviewer + +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." + +[[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 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, + 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 be considered as an 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 ensure + 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 an 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-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 +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 an "<>" 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:[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 +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 +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 notify `@in-toto/ITE-editors` +when they are ready to submit the ITE for <>. + +[[submission]] +==== Creating an ITE Submission + +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]. + +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 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 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 + 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 + +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. + +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. +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 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 +<>. +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 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. + +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. + +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 +technical quality of the ITE proposed. + +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 "<>", +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 +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 an ITE + +For an 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 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 an ITE has been accepted, the implementation must continue to progress +and eventually be completed. + +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. + +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 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 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, 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 +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 an 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]] +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 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 an 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]] +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]] +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 + +Whenever an ITE status changes, the "Status" field in the ITE document must be +updated. + +The possible paths of an ITE's status are as shown in Figure 1: + +.ITE Workflow +image::workflow.png[ITE Workflow] + +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 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 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. + +=== 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 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 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 + 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. ++ +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 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 + 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 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 an ITE to be approved as <>. + The prototype implementation must be sufficient to convey the viability of the design + 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 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. + +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 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 +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 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 +discussed prior to submission for pronouncement. + +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 +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 +in-toto-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 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 +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 an 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 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 +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 +decisions can't be reversed :)). + +[[Editor-responsibilities]] +=== ITE Editor Responsibilities & Workflow + +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 +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, 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). +. 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 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 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 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, +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, 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 ITEs. + +== 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 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. + +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' JEP + +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. + +=== 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 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. + +=== 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. + +== Testing + +There are no testing additions related to this ITE. + +== 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 0000000..51eb2b2 Binary files /dev/null and b/ITE/1/workflow.png differ