MEP 1
Title MEP purpose and guidelines
Status Accepted
Created 2014-11-13
Author Harm Aarts, Nicola Larosa

MEP purpose and guidelines

Abstract

This Monetas Enhancement Proposal (MEP) briefly describes the format future MEPs should be submitted in. The goal of having MEPs is to centralize past decisions and have a structured way of presenting them.

Current status

Currently there is no common place to record conclusions on significant changes to the software, nor is there a uniform, structured way of doing so.

Drawbacks

Having no structured way or place to view significant changes has several drawbacks:

  1. There is no efficient way of referring to past conclusions, leading to frustration and confusion.
  2. There is no way to know what is currently discussed and what the status might be.
  3. Not all the context is always present or evident: this could lead to misinterpretation.

Enhancement

This proposal proposes a way of recording made decisions in a central, self contained and uniform way. Some inspiration was had from BIP-0001 (in turn largely lifted from PEP 1).

Sections

A MEP must contain several sections:

A simple table containing metadata about the document. The keys in the table are:

  1. MEP: contains a unique identifier for the MEP. It must be an integer.
  2. Title: a descriptive title concisely summarizing the MEP.

  3. Status: tells in which state the document is currently in. Possible values are:

    1. 'Draft': the document is being discussed.
    2. 'Accepted': the proposal set forth in the MEP is accepted and should be acted upon.
    3. 'Rejected': the proposal is rejected after due discussion.

  4. Created: the date on which the MEP was first presented.

  5. Author: the original proposers of the MEP.

  6. Abstract section

This contains what every abstract contains: a short summary of the document, in this case the MEP.

This describes the current situation. The description should be as clear and self contained as possible.

Being self contained implies linking to other sources as reference only. Code snippets or protocol descriptions should be copied to a reasonable extent. The goal is to make the MEP understandable when read in a submarine.

The current status has drawbacks. While the 'Current status' section contains nothing more than a description, this section points out what is wrong with the status quo.

While the previous sections set the stage, this one contains the actual proposed solution. This, too, should be clear, self contained and as brief as possible.

However nice a proposed enhancement is, the cost of effecting the enhancement should explicitly be considered. This cost can be internal: code needs refactoring or documentation needs to be revised. The cost can also be external: backward compatibility could be broken or specifics should be communicated with the community.

Workflow

Once the subject matter has been adequately discussed and the need for a MEP is clear, the author will create a pull request adding a new MEP to the repository. The filename will contain the MEP number, left padded with zeros to three digits total, preferably using the next available one. The initial status will be "Draft".

After review, discussion and agreement, the status will be set to "Accepted" and the pull request will be merged. The new MEP will be announced on the Technical mailing list and the MEP will be effective from then on.

If no agreement can be reached the status will be set to "Rejected", and the pull request will still be merged for future reference. The MEP number will not be reused.

Changes to accepted MEPs will undergo the same evaluation process.

Impact

This MEP introduces a control process for significant changes to design and implementation.