BILI 1 -- BILI Purpose and Guidelines

BILI:	1
Title:	BILI Purpose and Guidelines
Author:	Justin Willis
Status:	Active
Type:	Process
Created:	2017-09-24
Last-Modified:	2017-09-24
Requires:
Required-By:
Replaces:
Replaced-By:
Blocks:
Blocked-By:
Related-To:

What is a BILI?
Types
Workflow
- Editors
- Genesis
- Submission
- Acceptance
- Maintenance
Template
- Preamble
- Contents
- Introduction
- Body
- References
- Example
Transferring Ownership
References

What is a BILI?

BILI stands for Because I Like It. A BILI is a standardization of a particular method, workflow, concept or idea. The BILI should provide a concise technical specification of the standard and a rationale for its adoption.

It is intend for BILIs to be the primary mechanisms for proposing major new development standards, for collecting community input on an issue, and for documenting the design decisions that go into project development. The BILI author is responsible for building consensus within the community and documenting dissenting opinions.

Types

There are three types of BILI:

A Standard BILI describes a new method, workflow, concept or idea.
An Informational BILI describes a developmental design issue, or provides general guidelines or information to the community, but does not propose a new standard. Informational BILIs do not necessarily represent a community consensus or recommendation, so developers are free to ignore Informational BILIs or follow their advice.
A Process BILI describes a process surrounding project development, or proposes a change to (or an event in) the development workflow. Process BILIs are like Standard BILIs but apply to areas other than the development workflow itself. They may propose an implementation, but not to a project's codebase; they often require community consensus; unlike Informational BILIs, they are more than recommendations, and developers 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 project development. Any meta-BILI is also considered aProcess BILI.

Workflow

Editors

The BILI editors are individuals responsible for managing the administrative and editorial aspects of the BILI workflow. BILI editorship is by invitation only and will be provided by the current editors.

The current editors are:

Justin Willis

Genesis

The BILI process begins with a new idea for project development. It is highly recommended that a single BILI contain a single key proposal or new idea. Small enhancements or patches often don't need a BILI and can be added to a project's development workflow by using that project's issue tracker. The more focused the BILI, the more successful it tends to be. The BILI editors reserve the right to reject BILI proposals if they appear too unfocused or too broad. If in doubt, split your BILI into several well-focused ones.

Each BILI must have an author -- someone who writes the BILI using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The BILI author should first attempt to ascertain whether there is an already existing BILI and then if the idea is BILI-able.

Vetting an idea publicly before going as far as writing a BILI is meant to save the potential author time. Many ideas have been brought forward for changing project development that have been rejected for various reasons. Asking the 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.

Once the author has asked the community as to whether an idea has any chance of acceptance, a pull request should be started presenting the proposed BILI.

Submission

Following a discussion about a proposed standardization, the proposal should be submitted in a pull request. The proposal must be written in BILI style as described below, else it will fail acceptance immediately (although minor errors may be corrected by the editors).

The standard Workflow is:

You, the BILI author, fork this website's repository ^[1], and create a file named bili_XXXX.html in the bilis directory that contains your new BILI. Choose the next available BILI number in the sequence and substitute that for "XXXX". Be sure to pad the BILI number with the appropriate number of zeros to maintain four digits.
Append your new BILI to BILI 0 in both indexes taking careful note which category you place the BILI into.
Push this to your fork, assign your proposed BILI a status of "Draft" and submit a pull request.
The BILI editors review your pull request for structure, formatting, and other errors.
Your BILI will be discussed and if approved, labeled as either Standard, Informational, or Process. You may be asked to change the BILI number if another BILI has been accepted during this time.
Once the acceptance process is complete, and the BILI editors approve it, your BILI will be merged into master.

The BILI editors will not unreasonably deny a BILI. Reasons for denying BILI status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not adhering to general project development workflow standards.

As updates are necessary, the BILI author can check in new versions by submitting an additional pull request with their proposed modifications. This new pull request will go through the same acceptance process as a new BILI.

BILI authors are responsible for collecting community feedback on a BILI before submitting it for acceptance.

Acceptance

For a BILI to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed standard and the standard must represent a net improvement.

Once a BILI has been accepted, the status will be changed to "Final".

A BILI can also be assigned a status of "Deferred". The BILI author or an editor can assign the BILI this status when no progress is being made on the BILI. Once a BILI is deferred, the BILI editor or author can re-assign it to draft status.

A BILI can also be "Rejected". Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact. The "Withdrawn" status is similar - it means that the BILI author themselves have decided that the BILI is actually a bad idea, or has accepted that a competing proposal is a better alternative.

When a BILI is Accepted, Rejected or Withdrawn, the BILI should be updated accordingly. In addition to updating the status field, at the very least the list of references should be updated to include all relevant information and conversations.

BILIs can also be superseded by a different BILI, rendering the original obsolete. This is intended for Informational BILIs, where version 2 of an API can replace version 1.

The possible paths of the status of BILIs are as follows:

Some Informational and Process BILIs may also have a status of "Active" if they are never meant to be completed. E.g. BILI 1 (this BILI).

Maintenance

In general, Standard BILIs are no longer modified after they have reached the Final state. Once a BILI has been completed, the projects become the formal documentation of the expected behavior.

Informational and Process BILIs 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 BILI being updated.

Template

Each BILI should have the following parts in this order:

Title -- A short descriptive title
Preamble -- A formatted table containing the BILI number, the title, the author, the status, the type, the date created, any BILI numbers that the BILI requires, is required-by, replaces, is replaced-by, blocks, is blocked-by, is related-to, and the BILI's last-modified date.
Contents -- An ordered table of contents with links to each section.
Introduction -- A short (~200 word) description of the proposed standard and why it is important.
Motivation -- A clear explanation about why the BILI is being proposed.
Content -- The content of the proposed BILI separated into constituent sections.
Rationale -- A description about why the BILI is proposed the way it is.
References -- A list of all relevant information used when constructing the proposed BILI.

Preamble

Each BILI must begin with a formatted table containing the BILI number, the title, the author, the status, the type, the date created, any BILI numbers that the BILI requires, is required-by, replaces, is replaced-by, blocks, is blocked-by, is related-to, and the BILI's last-modified date.

Here is an example:

              
<div class="row">
  <table id="preamble" class="table table-hover">
    <tbody>
      <tr>
        <td>BILI:</td>
        <td>XXXX</td>
      </tr>
      <tr>
        <td>Title:</td>
        <td>Title</td>
      </tr>
      <tr>
        <td>Author:</td>
        <td>John Doe</td>
      </tr>
      <tr>
        <td>Status:</td>
        <td>Draft</td>
      </tr>
      <tr>
        <td>Type:</td>
        <td>Informational</td>
      </tr>
      <tr>
        <td>Created:</td>
        <td>1970-01-01</td>
      </tr>
      <tr>
        <td>Last-Modified:</td>
        <td>1970-01-01</td>
      </tr>
      <tr>
        <td>Requires:</td>
        <td></td>
      </tr>
      <tr>
        <td>Required-By:</td>
        <td></td>
      </tr>
      <tr>
        <td>Replaces:</td>
        <td></td>
      </tr>
      <tr>
        <td>Replaced-By:</td>
        <td></td>
      </tr>
      <tr>
        <td>Blocks:</td>
        <td></td>
      </tr>
      <tr>
        <td>Blocked-By:</td>
        <td></td>
      </tr>
      <tr>
        <td>Related-To:</td>
        <td></td>
      </tr>
    </tbody>
  </table>
</div>

The BILI number should be the next available in sequence and may be reassigned prior to approval.

All dates should be written in ISO 8601 ^[2] date format.

The initial status of a newly proposed BILI should be "Draft"

The BILI type should be chosen from the following list:

Standard
Informational
Process

Following the preamble, each BILI must contain an ordered table of contents linking together the constituent parts of the proposal.

Here is an example:

              
<div class="row">
  <h2 id="contents">Contents</h2>
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#motivation">Motivation</a></li>
    <li>
      <a href="#section_1">Section 1</a>
      <ul>
        <li><a href="#subsection_a">Subsection A</a></li>
        <li><a href="#subsection_b">Subsection B</a></li>
        <li><a href="#subsection_c">Subsection C</a></li>
      </ul>
    </li>
    <li><a href="#section_2">Section 2</a></li>
    <li><a href="#section_3">Section 3</a></li>
    <li><a href="#rationale">Rationale</a></li>
    <li><a href="#references">References</a></li>
  </ul>
</div>

Body

Following the contents, each BILI will describe its proposal in constituent parts linking to the table of contents. Use this general template for the body, introduction, motivation, and rationale sections.

Here is an example:

              
<div class="row">
  <h2 id="section_1">Section 1</h2>

  <h3 id="subsection_a">Subsection A</h3>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>

  <h3 id="subsection_b">Subsection B</h3>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>

  <h3 id="subsection_c">Subsection C</h3>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

Each line in the BILI should never exceed 80 characters in length, but only in rare circumstances.

References

Following the rationale, each BILI should list any and all relevant information used during its construction.

Here is an example:

              
<div class="row">
  <h2 id="references">References</h2>
  <ol>
    <li id="ref_1">
      <a href="https://example.com">
        <i>Reference 1</i>
      </a>, Sample, Lorem ipsum dolor sit amet.
    </li>
  </ol>
</div>

If you decide to reference a reference in your BILI, do so like this:

              
<a href="#ref_1"><sup>[1]</sup></a>

Always use HTTPS links if they are available.

Example

Here is a complete example BILI for reference:

              
<div class="row">
  <div class="col-lg-12">
    <div class="page-header">
      <h1 id="title">BILI XXXX -- Title</h1>
    </div>
  </div>
</div>

<div class="row">
  <table id="preamble" class="table table-hover">
    <tbody>
      <tr>
        <td>BILI:</td>
        <td>XXXX</td>
      </tr>
      <tr>
        <td>Title:</td>
        <td>Title</td>
      </tr>
      <tr>
        <td>Author:</td>
        <td>John Doe</td>
      </tr>
      <tr>
        <td>Status:</td>
        <td>Draft</td>
      </tr>
      <tr>
        <td>Type:</td>
        <td>Informational</td>
      </tr>
      <tr>
        <td>Created:</td>
        <td>1970-01-01</td>
      </tr>
      <tr>
        <td>Last-Modified:</td>
        <td>1970-01-01</td>
      </tr>
      <tr>
        <td>Requires:</td>
        <td></td>
      </tr>
      <tr>
        <td>Required-By:</td>
        <td></td>
      </tr>
      <tr>
        <td>Replaces:</td>
        <td></td>
      </tr>
      <tr>
        <td>Replaced-By:</td>
        <td></td>
      </tr>
      <tr>
        <td>Blocks:</td>
        <td></td>
      </tr>
      <tr>
        <td>Blocked-By:</td>
        <td></td>
      </tr>
      <tr>
        <td>Related-To:</td>
        <td></td>
      </tr>
    </tbody>
  </table>
</div>

<div class="row">
  <h2 id="contents">Contents</h2>
  <ul>
    <li><a href="#introduction">Introduction</a></li>
    <li><a href="#motivation">Motivation</a></li>
    <li>
      <a href="#section_1">Section 1</a>
      <ul>
        <li><a href="#subsection_a">Subsection A</a></li>
        <li><a href="#subsection_b">Subsection B</a></li>
        <li><a href="#subsection_c">Subsection C</a></li>
      </ul>
    </li>
    <li><a href="#section_2">Section 2</a></li>
    <li><a href="#section_3">Section 3</a></li>
    <li><a href="#rationale">Rationale</a></li>
    <li><a href="#references">References</a></li>
  </ul>
</div>

<div class="row">
  <h2 id="introduction">Introduction</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="motivation">Motivation</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="section_1">Section 1</h2>

  <h3 id="subsection_a">Subsection A</h3>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>

  <h3 id="subsection_b">Subsection B</h3>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>

  <h3 id="subsection_c">Subsection C</h3>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="section_2">Section 2</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="section_3">Section 3</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="rationale">Rationale</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="rationale">Rationale</h2>
  <p>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin sed tempus
    ligula. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
    per inceptos himenaeos. Quisque leo ante, gravida vel commodo et, elementum
    sit amet neque. Sed eleifend, lorem quis mollis accumsan, lacus leo ultrices
    arcu, nec faucibus elit urna eu ligula. Vivamus sit amet tristique dui.
    Integer dignissim viverra consequat. Nullam tincidunt neque sed eros
    tristique, a hendrerit sem ullamcorper.
  </p>
</div>

<div class="row">
  <h2 id="references">References</h2>
  <ol>
    <li id="ref_1">
      <a href="https://example.com">
        <i>Reference 1</i>
      </a>, Sample, Lorem ipsum dolor sit amet.
    </li>
  </ol>
</div>

Transferring Ownership

It occasionally becomes necessary to transfer ownership of BILIs to a new author. In this situation the original author(s) will remain as co-author(s) of the transferred BILI given that the original author agrees to the transfer.

A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the BILI process, or has gone rouge (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because the author doesn't agree with the direction of the BILI. One aim of the BILI process is to try to build consensus around a BILI, but if that's not possible, an author can always submit a competing BILI.

If you are interested in assuming ownership of a BILI, you should follow the submission procedure to update the BILI in question. You should also contact the original author(s) and a BILI editor.

References

Website Repository , Bitbucket, Bkvaluemeal.bitbucket.io.
ISO 8601 , XKCD, ISO 8601.
PEP 1 , Python Enhancement Proposal, PEP Purpose and Guidelines.