ITE |
1 |
Title |
in-toto Enhancement format |
Sponsor |
|
Status |
Active 😄 |
Type |
Process |
Created |
2018-10-04 |
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.
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 Sponsor. 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 Contributors 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 [1].
|
ℹ️
|
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. |
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.
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 ITE Editor Responsibilities & Workflow 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 [1] and
pull 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 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.
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.
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."
ITE documents must follow RFC 2119, which defines key words to "indicate requirement levels". These are listed below:
-
MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
-
MUST NOT This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition of the specification.
-
SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
-
SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
-
MAY This word, or the adjective "OPTIONAL", mean that an item is truly optional.
|
ℹ️
|
When choosing to go counter to SHOULD or SHOULD NOT guidance, the reasons behind that choice SHOULD be documented. |
Before delving into the details of the ITE workflow, let’s take a high-level look at how ITE might go.
-
Initial Discussion - 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 "Sponsor" for this potential ITE. She gathers initial feedback from the community, adjusts her design as needed, records the reasons for design choices, and keeps track of differing views. Kelly, an expert in the area for this ITE, volunteers to be the Editor for this ITE.
-
Submission - 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 ITE Editors for approval as a Draft 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 "Draft" ITE.
-
Draft Status - While the ITE is a "Draft", Andrea continues to gather feedback, change the proposal, and record the reasoning and differing views. At the same time, she and other contributors continue expanding and refining the prototype implementation as needed to match the current state of the 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 Reviewer, in this case the Editor Kelly, to review the ITE for Acceptance.
-
Review - 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 "Accepted" ITE.
-
Accepted Status - Andrea and other contributors complete all remaining implementation related to the "Accepted" ITE (code, documentation, or other changes). The specification is updated and a reference to this ITE is added.
-
Final Status - 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 "Final" (or in some cases "Active"). The ITE is done.
-
Maintenance - At some later date, the ITE may need to be updated with minor changes and clarifications. As Sponsor 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 original or might replace it.
-
Other Outcomes - Not all ITEs will be accepted and finalized. Other possible outcomes include "Rejected", "Deferred", "Withdrawn".
|
❗
|
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. |
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.
|
ℹ️
|
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 |
Each ITE must have a "Sponsor" — 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 [2] is 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 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 approval as Draft.
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 [1].
|
❗
|
All submissions must go through pull request, even those by Editors or contributors with "git push" privileges for the ITE repository [1]. |
To submit an ITE for approval as Draft, the ITE Sponsor should:
-
Fork the ITE repository [1].
-
Clone their forked repository locally.
-
Create a new branch called
ite-submissionin their clone. -
Copy the folder
ITE-template/0000toITE/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/masterbranch. -
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.
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.
|
❗
|
"Approval as Draft" is not the same as accepting the ITE. "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 Required Sections
The Reviewer 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
Editors' "Approve as Draft" section.
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,
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 [1] 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 ITE Editor Responsibilities & Workflow). This includes ensuring the initial version meets the expected standards for 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 [1],
and submit pull requests targeting the master branch.
Once the Sponsor believes an ITE meets at least the minimum criteria to be "Accepted", they request the ITE to be reviewed for acceptance, usually via an email to the in-toto-dev@googlegroups.com mailing list. The ITE Reviewer and their chosen consultants then review the ITE. If the Reviewer agrees that ITE is ready, they mark the ITE as "Accepted". 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.
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 opinions.
-
clearly define the scope and features of the proposed enhancement.
-
describe a completed design that addresses 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 References 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 review again for acceptance.
When the implementation is complete and incorporated into the appropriate "main" code repository, the ITE Sponsor will change the ITE’s status to "Final".
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
-
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 Superseded-by header must be filled in with a link to the new ITE.
Not all ITEs will be accepted and finalized.
- Rejected
-
An ITE Reviewer 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 Accepted ITE may ultimately be rejected at some point before it reaches "Final" status, due to factors not known at the time it was Accepted.
Upon the request of the Sponsor, the Reviewer may choose to return a Rejected ITE to Draft status, but this is at the discretion of the Reviewer.
- Withdrawn
-
An ITE Sponsor 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
-
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.
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:
When an ITE is Accepted, Rejected or Withdrawn, a "Resolution" 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.
Except for decisions by an ITE’s Reviewer, the ITE process is run by consensus. It is the responsibility of every contributor to respect other contributors, listen to their perspectives, and attempt to find solutions that work for everyone.
If consensus cannot be achieved on an ITE, contributors may request that the ITE Reviewer intervene. The Reviewer will consider the matter, and render their decision, including describing what actions will be taken and documenting their reasoning.
All ITEs MUST have the following parts to be "approved as Draft":
-
Metadata - table containing the ITE Header Preamble 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 Refining a Draft ITE. The prototype implementation must be sufficient to convey the viability of the design for an ITE to be Accepting an ITE. 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.
|
|
ITE submissions that do not adequately complete any of the above sections will not be approved as ITE Drafts. |
As noted before, ITEs may be modified at all stages except when they are marked final. When an ITE that is marked accepted or active is changed, a Changelog section must be added to the document if one is not present already. Every change made to the ITE must be accompanied by a dated entry in this section that describes the change.
The final implementation must include test code and documentation appropriate for either the in-toto user or developer documentation.
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.
ITEs are UTF-8 encoded text files using the 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.
All ITEs MUST begin with an AsciiDoc table containing metadata relevant to the ITE:
.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
0000until one is assigned. -
Title — Brief title explaining the proposal in fewer than 50 characters.
-
Sponsor — Sponsor of the ITE, in essence, the individual responsible for seeing the ITE through the process.
-
Status — Draft 💬, Deferred ⌛, Accepted 👌, Rejected ⛔, Withdrawn ✋, Final 🔒, Replaced 🗡️, Active 😄.
-
Type — Describes the type of ITE: Standards, Informational, Process.
-
Created — Date (
%Y-%m-%d) when the document was first created.
- Issue
-
An issue identifier row is available to specify a linked placeholder for an issue in GitHub, if any.
- 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
-
ITEs may have a Requires row, indicating the ITE numbers that this ITE depends on.
- Replaces
-
An ITE that replaces another ITE must have a Replaces row containing the number of the ITE that it rendered obsolete.
- 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
-
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.
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 [1] or the in-toto issue tracker [3]. 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.
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, [1] make the sponsorship modification, and submit a pull request. At the same time, send a message asking to take over, addressed to both the original Sponsor and the 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 :)).
An ITE Editor must subscribe to the in-toto-dev@googlegroups.com list and must watch the ITE repository [1]. 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).
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.
If the ITE isn’t ready, an Editor will send it back to the Sponsor for revision with specific instructions.
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
masterbranch.
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.
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.
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.
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.
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.
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.
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.
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. Furthermore, the repository structure of JEP was adopted, as it allows for the addition of self-hosted diagrams and supporting documents.
There are a number of possible asciidoc style guidelines. For example, there are a number of reasons to use one sentence per line, one phrase per line, or other specific formatting. However, choosing which guideline to require, recommend, or even make optional, is a potentially long and difficult process. Instead of bogging down this ITE in that process, we decided to consider asciidoc style and formatting guidelines in a later ITE.
There are no new infrastructure requirements related to this proposal. This ITE leverages existing infrastructure.
-
Jan 9, 2023: Created a changelog requirement for modifications to accepted and active ITEs.