# Security API (SecAPI) RFCs
## Table of Contents
+ [RFC Process Considerations](#rfc-process-considerations)
+ [RFC Process](#rfc-process)
+ [RFC Life Cycle](#rfc-life-cycle)
+ [Leaders](#leaders)
+ [Format Conventions](#format-conventions)
+ [Terminology](#terminology)
Many changes, including bug fixes and documentation improvements can be implemented and reviewed via
the normal GitHub pull request workflow.
Some changes though are "substantial", and we ask that these be put through a design process and
produce a consensus among the Comcast TCP (Trusted Computing Products) team.
The "RFC" (Request for Comments) process is intended to provide a consistent and controlled path for
new features to enter the project. The process allows for technical discussion and creating
consensus on new features prior to implementation across different platforms in different languages.
This RFC process is used to make feature and interface proposals to the Security API.
This process is under **active development** and feedback is encouraged on how we can improve on
feature development and collaboration across platforms.
## RFC Process Considerations
You should consider using this process if you intend to make "substantial" changes to the Security
API. What constitutes a "substantial" change is evolving based on community norms and varies
depending on what part of the ecosystem you are proposing to change, but may include the following:
- Any addition, removal, or change to a public API.
- A new feature that creates or changes a public API, and may require a feature flag if introduced.
- The removal of features that already shipped as part of the release channel.
The RFC process can also be helpful to encourage discussions about a proposed feature as it is being
designed, and incorporate important constraints into the design while it's easier to change, before
the design has been fully implemented.
## RFC Process
In short, to get a major feature added to the SecAPI, one usually first gets the RFC merged into the
RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with the goal
of eventual inclusion into the SecAPI.
* First, search prior proposals and proposals that have been denied in the past before proposing
something new. These can be found by browsing closed and merged pull requests.
* For those with write access to main repository (**Placeholder for rfc repo here**), create a
branch to hold your proposed RFC. For those without write access, create a fork of the main
repository.
* Copy `0000-template.md` to `accepted/0000-my-feature/README.md` (where 'my-feature' is
descriptive. don't assign an RFC number yet).
* Fill in the RFC. Put care into the details: **RFCs that do not present convincing motivation,
demonstrate understanding of the impact of the design, or are disingenuous about the drawbacks or
alternatives tend to be poorly-received**.
* All images and other supporting artifacts linked directly from the RFC markdown should be placed
within the RFC-specific directory
* Submit a pull request. As a pull request the RFC will receive design feedback from the larger
SecAPI user community, and the author should be prepared to revise it in response.
* Build consensus and integrate feedback. RFCs that have broad support are much more likely to make
progress than those that don't receive any comments.
* RFCs rarely go through this process unchanged, especially as alternatives and drawbacks are shown.
You can make edits, big and small, to the RFC to clarify or change the design, but make changes as
new commits to the pull request, and leave a comment on the pull request explaining your changes.
Specifically, do not squash or rebase commits after they are visible on the pull request.
* Eventually, through considering many factors such as resource constraints and team priorities, the
team will decide whether the RFC is a candidate for inclusion into the SecAPI.
* At this point, a **Leader**, who is a member of the Comcast TCP team, will be assigned to the RFC
using the GitHub assignee feature. See below for details on responsibilities of RFC Leaders.
* At the Leaders discretion, the RFC will enter a "final comment period" (FCP) lasting 7 days. The
beginning of this period will be signaled with a comment and tag on the RFC's pull request.
* An RFC can be modified at the end of the FCP based upon feedback from the team and community.
Significant modifications may trigger a new final comment period. This should be decided by the
RFC Leader.
* An RFC may be rejected by the team after public discussion has settled and comments have been made
summarizing the rationale for rejection. The Leader should then close the RFC's associated pull
request. A comment is included in the pull request that shows the pull request was rejected.
* An RFC may be accepted at the close of its final comment period. The Leader will merge the RFC's
associated pull request, at which point the RFC will become 'active'.
## RFC Life Cycle
Once an RFC becomes active, then authors may implement it and submit the feature as a pull request
to the appropriate repo. Becoming 'active' is not a rubber stamp, and in particular still does not
mean the feature will ultimately be implemented and merged; it does mean that the core team has
agreed to it in principle and are amenable to implementing it.
Furthermore, the fact that a given RFC has been accepted and is 'active' implies nothing about what
priority is assigned to its implementation, nor whether anybody is currently working on it.
Modifications to active RFC's can be done in follow up PR's. We strive to write each RFC in a manner
that it will reflect the final design of the feature; but the nature of the process means that we
cannot expect every merged RFC to actually reflect what the end result will be at the time of the
next major release; therefore we try to keep each RFC documented somewhat in sync with the feature
as planned, tracking such changes via follow up pull requests to the document.
## Leaders
There are no restrictions on who can submit proposals to the repo, provided they follow the process
outlined above. For this reason, a "Leader", who is a member of the Comcast TCP team, will be
assigned according to the process above, and is expected to fulfill the following responsibilities:
* Tracking the feedback and keeping the proposal in check with the discussions. This means that the
Leader often collaborates with the proposal author on the text of the proposal.
* Moves the proposal into the FCP state and makes an announcement to the team.
* Merges or closes the proposal PR as necessary.
* Acts as the point of contact and subject matter expert when development teams move forward with
implementation.
If an RFC is submitted by a member of the Comcast TCP team, they may assign themselves as the Leader
once it is decided the proposal is a candidate for inclusion. However, this is not required and may
be passed to another volunteer.
A member of the Comcast TCP team may volunteer, or one may be assigned, if a proposal is made by
someone outside of the team.
If desired, this role may be shared by two or more members of the team.
## Format Conventions
RFCs are submitted in markdown format, and follow the following conventions:
* Maximum line length is 100 characters.
* Single space after period before next sentence.
* Blank line between a section header and the header text.
## Terminology
Definitions of commonly used terms in RFCs to avoid any ambiguity and confusion in RFC descriptions.