11 KiB
IFA Proposal: 0
Title: IFA Proposal Guidelines & Process
Author: Zachary Lym "indolering" <zachlym@indolering.com>
Status: Draft
Type: Process
Created: 2015-05-25
Table of Contents
Abstract
The Internet Freedom Alliance Working Group (IFA-WG) is an organization designed to promote collaboration between projects that empower online civil rights. IFA proposals are modeled after IETF RFCs and seek to create shared standards that are used by multiple projects, reducing duplicative work and combating insular decision making.
Types
There are three kinds of proposals:
- A Standards Track Proposal describes new standards and changes to existing standards that impact multiple implementations, such as DNS records for decentralized TLDs.
- An Informational Proposal provides general guidelines or information to the community, but does not propose a new feature. Informational Proposals do not necessarily represent community consensus or recommendation, so users and implementors are free to ignore Informational Proposals or follow their advice.
- A Process Proposal describes a process surrounding the proposal creation process. Unlike Informational Proposals, 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 used to format proposals.
Proposal Workflow
Each proposal must have a champion – someone who writes the proposal and attempts to build community consensus around the idea. A champion should publicly vet the idea before going as far as writing a proposal.
An proposal champion should begin writing their proposal by forking the IFA-WG proposals repo and following the formatting instructions found in this proposal (IFA-0).
When complete, assign the proposal a number (usually by incrementing form the most recent proposal), update the listing of active proposals in the README.md file, perform the post-professing steps outlined in README.md, and submit a pull request.
Status
The possible paths for a Draft proposals are as follows:
The arrow diagrams are not absolutes, a Withdrawn or Rejected proposal can regain Draft status, but this is very rare. Statuses that are grey indicate that the proposal will be removed from the list of current proposals.
- Draft
- If a proposal is not rejected outright, it attains Draft status and the reference number becomes permanently reserved for that proposal. A Draft proposal can be updated using pull requests. The Git revision history serves as the historical record of the proposal.
- Deferred
- When a Draft proposal lacks consistent progress it becomes deferred. Deferred is not necessarily a bad thing, it may be that other standards are being worked on first.
- Accepted
- Rough consensus is reached to adopt a Draft Standards Track Proposal and work on a reference implementation is in progress. Note that in some cases it may be prudent to complete a reference implementation when the proposal is still a Draft. Informational and Process Proposals that intend to be updated in the future (such as this proposal) retain Accepted status.
- Final
- In the case of Standards Track Proposals, Final status indicates that the reference implementation is complete. Informational and Process Proposals that are *not* intended to be updated should be marked as Final and Superseded by new proposals.
- Rejected
- Rough consensus to reject a proposal can come about as a response to a Draft proposal or after a proposal was Accepted but then Rejected after attempting to implement it. A section summarizing the reason for rejection and links to relevant discussions **must** be appended to the proposal.
- Withdrawn
- Status of when a Draft proposal has been withdrawn by the author. Authors/editors **should** append a section summarizing the reason for withdrawal and links to relevant discussions.
- Superseded
- When an Accepted or Final proposal has been replaced by another proposal. Editors **must** link to new proposal in the header of the document (as outlined in the [Proposal Header](#proposal-header) section).
Rejection
An editor can reject a proposal without wider discussion for any number of reasons, including:
- Being too broad.
- Not relying on existing standards/duplicating effort.
- Incorrect formatting.
- Not providing proper motivation.
- Not having consulted relevant communities.
Note that IFA proposals are designed to facilitate collaborate across communities, so the consultation requirement is fairly shallow.
Discussion
Prior to submitting a proposal for Draft status, the primary means of communication for the relevant communities should be used. However, Draft proposals should attempt to funnel discussion into issue tickets on the IFA proposal repository. Issue tickets must link/reference the proposal and should link to relevant external discussions.
Content
Proposals are designed to codify standards, either proposed or existing. Each proposal should strive to embody a single key proposal or new idea. Whenever possible, proposals should defer and link to existing standards, even when those standards are external (such as an IETF RFC).
Sections
Each proposal should contain the following sections when appropriate:
-
Header -- RFC 822 style headers containing meta-data about the proposal, including the proposal number, a short descriptive title (ideally 42 characters), the names, and optionally the contact info for each author, etc.
-
Abstract -- a short (~200 word) description of the technical issue being addressed.
-
Specification -- The technical specification should describe the syntax and semantics. The specification should be detailed enough to allow competing, interoperable implementations.
-
Motivation -- The motivation is critical for a proposal that wants to alter existing standards. It should clearly explain why the existing specification is inadequate to address the problem that the new proposal solves. Proposals without sufficient motivation may be rejected without being assigned draft status.
-
Rationale -- The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages.
-
The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
-
Backwards Compatibility -- All standards that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The standard must explain how the author proposes to deal with these incompatibilities. Proposals without a sufficient backwards compatibility treatise may be rejected without being assigned draft status.
-
Reference Implementation -- A reference implementation must be completed before any standard is given status "Final", but it need not be completed before the standard is accepted. It is usually better to finish the specification and rationale first and reach consensus on it before writing code.
-
The final implementation must include test code and documentation.
Format
-
Proposals should be written in Github flavored markdown and allowed inline HTML.
-
Links should use the
[content][ref]format and references should appear at the end of the section in which they are used. -
Image files should be included in a subdirectory with a name reflecting that of the proposal number (i.e.
ifa-0001). -
When appropriate, include a DocToc markup for a Table of Contents after the header:
Proposal Header
Each proposal must begin with the following header, lines marked with an asterisk are optional.
IFA Proposal: <Proposal number>
Title: <Proposal title>
Author: Real Name "optional username" <real@example.tld>
Anonymous Handle <user@example.tld>
Status: Draft | Accepted | Final | Deferred |
Withdrawn | Rejected | Superseded
Type: Standards Track | Informational | Process
Created: yyyy-mm-dd
* Replaces: <Proposal number>
* Superseded-By: <Proposal number>
* Resolution: <link to announcement>
####Authors
Real names must be used unless the author is anonymous.
####Created
The Created header should record the date of the initial pull request.
####Resolution
The Resolution header is required for Standards Track Proposal only. It contains a URL that should point to the pronouncement about the proposal and when it will go into effect.
Copyright
All proposals must be licensed as CC0, although we are waiving the requirement to label each individually.
Proposal Editor Responsibilities
After PR for a proposal pull has been submitted, an editor does the following:
- Read the proposal 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.
- Ensure that the title should accurately describe the content.
- Edit the proposal for language (spelling, grammar, sentence structure, etc.), markup, and code style.
- If the proposal isn't ready, the editor will not assign a number nor draft status. Instead, they should reject the PR but feedback and specific instructions for the author.
- If the proposal is ready, ensure that the Draft number is accurate, update the list of current proposals found in the README file, and merge the PR.
Proposal editors are not critics, their job is to facilitate the process through constructive feedback and to perform administrative functions.