HEEP: 0001
Title: HEEP Purpose and Guidelines
Version: 0.1
Last-Modified: 10-04-2016
Author: Renato Massaro <r@ena.to> 
Status: Active
Type: Meta
Content-Type: text/markdown
Created: 10-04-2016

What is a HEEP?

HEEP stands for Hacker Experience Enhancement Proposal. A HEEP is a design document providing information, describing a new feature or proposing new processes to the Hacker Experience community. It is almost a copy of Python's PEP.

We intend HEEPs to be the primary mechanisms for proposing major new features and for documenting the design and building decisions that have gone into Hacker Experience. The HEEP author is responsible for building consensus withing the community and documenting dissenting opinions.

Because the HEEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.

HEEP Types

There are four kinds of HEEPs:

  • A Feature HEEP describes a new feature, implementation or extension to the defined scope.
  • An Informational HEEP describes an issue or provides general guidelines or information to the Hacker Experience community, but does not propose a new feature. Informational HEEPs do not necessarily represet a community consensus or recommendation, so users and contributors are free to ignore Informational HEEPs or follow their advice.
  • A Process HEEP describes procedures, guidelines or proposes changes to the active Hacker Experience development workflow. Unlike Informational HEEPs, they are more than recommendatio and users are typically not free to ignore them. Therefore, they often require community consensus.
  • A Research HEEP is a "sandbox" proposal to test and experiment on wacky ideas. These often require significative research, experimentation and community feedback before they are ready to be proposed as another type of HEEP. Research HEEPs are also useful when the purpose is to obtain a deeper understanding of the problem and possible solutions that can later support a concrete enhancement proposal.

HEEP Scope

No matter which type a HEEP has, it must be applied to at least one scope. There are four kinds of scopes:

  • The Meta scope applies to HEEPs that change the way Hacker Experience is developed and built. For instance, this HEEP is under the Meta scope.
  • The Core scope applies to changes on the Core software and are usually code-related.
  • The Interface scope applies to changes on any of the many user interfaces we might have.
  • The Design scope applies to changes on design, mechanics or features of Hacker Experience.

HEEP Parties


The acronym BDFL stands for "Benevolent Dictator for Life" and refers to Renato Massaro, the original creator of, and final design authority for, Hacker Experience.

HEEP Board

The HEEP Board are individuals responsible for managing the administrative and editorial aspects of the HEEP workflow, and for voting for or against HEEPs that are sent to review. The current board members are:

  • Renato Massaro
  • Charlotte Oliveira

HEEP membership is by invitation of the current members. We plan to add at least three more members as top contributors start getting distinguished.

HEEP champion

Each HEEP must have a champion -- someone who writes the HEEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. If no champion is assigned, we assume the author to be the HEEP champion.

The HEEP workflow

Step 0 - Validating the idea/enhancement

The HEEP workflow begins with a new idea for Hacker Experience.

We highly recommend that the author get an overall sentiment of the community about the idea/enhancement. Sometimes the change is so small that a HEEP doesn't need to be created. Maybe a related HEEP already exists. This early feedback can save the potential author a lot of time.

To validate your idea, procedure or feature request, create a task with the HEEP-Feedback tag describing its purpose and motivations.

Vetting an idea publicly before going as far as writing a HEEP is meant to save the potential author time. It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it is good for most people.

Step 1 - Draft the proposal with the community

The next step is to draft the HEEP with community feedback. This gives the author a chance to flesh out the draft HEEP to make properly formatted, of high quality, and to address initial concerns about the proposal.

To submit your draft, create a task under the HEEP-Draft tag with your draft. Iterate with the community to improve your draft.

Step 2 - Obtain the HEEP status

Once you feel your draft is ready to be reviewed, submit it to the HEEP Board by adding the HEEP-Proposal tag to your task created previously.

On the next meeting, the board will analyze if your HEEP follows the requirements and have no red flags.

The draft must be written in HEEP style as described in HEEP Formatting, else it will be denied without further regard until proper formatting rules are followed (although minor errors will be corrected by the Board).

If the HEEP Board members approve, they will assign the HEEP a number, give it "Draft" status, and check-in the initial draft to the repository.

The board will not unreasonably deny a HEEP. Reasons for denying HEEP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the Hacker Experience philosophy. The BDFL can be consulted during the approval phase, and is the final arbiter of the draft's HEEP-ability.

Step 3 - Iterate on your HEEP Draft

If the board accepts your draft, it will be assigned a HEEP number and officialy receive the Draft status.

After the HEEP receives Draft status, board members and community start a series of iterations with the author to give feedback and improve the HEEP.

As updates are necessary, the HEEP author can submit patches with new versions of the HEEP draft.

Step 4 - Submit your Draft for review

Once you feel your Draft is ready and complete, submit it for review by adding the tag HEEP-Review.

Then, board members will comment your task with a link to a Wiki page containing each members' arguments, and to a poll where the community can vote for or against the HEEP.

The board's final decision count as one vote, and the community overall sentiment counts as one vote too. If we reach a draw, the BDFL will have the ultimate say on it. A new HEEP may be created to establish a better voting process, since "community overall sentiment" is too abstract.

Once community and board members reach a consensus, the HEEP will receive the Accepted or Active status.

HEEP Format

Single Responsibility

It is highly recommended that a single HEEP contain a single key proposal or new idea. Small enhancements or patches often don't need a HEEP and can be injected into the Hacker Experience development workflow with a patch submission to the Hacker Experience Development Center. The more focused the HEEP, the more successful it tends to be. The HEEP Board reserve the right to reject HEEP proposals if they appear too unfocused or too broad. If in doubt, split your HEEP into several well-focused ones or ask for feedback.

Each HEEP must begin with a header preamble. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All others are required.

HEEP: Title: Version: Last-Modified: Author: Discussion: Status: Type: Scope: Requires: Created: History: Replaces: * Superseded-By:

The Author header lists the names, and optionally the email addresses of all the authors/owners of the HEEP. The format of the Author header value must be

John Doe <john@dom.ain>

or, if the email is not included, simply

John Doe