---
mep:
id: 1
author:
- Please add your names here!
- Chris Sewell @chrisjsewell
created: "2022-11-XX"
type: Process
status: Active
# discussions-to: https://github.com/executablebooks/myst-eps/discussions/2
---

NOTE: There is active conversaion here on a simplified process:

https://github.com/executablebooks/meta/pull/843

# MEP Purpose and Guidelines

## What is a MEP?

MEP stands for MyST Enhancement Proposal.
A MEP is a design document providing information to the MyST community,
or describing a new feature for MyST or its processes or environment.
The MEP should provide a concise technical specification of the feature and a rationale for the feature.

We intend MEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into MyST.
The MEP author is responsible for building consensus within the community and documenting dissenting opinions.

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

## MEP Audience

The typical primary audience for MEPs are the core developers of the MyST ecosystem,
as well as developers of other MyST compliant tools.

However, other parts of the MyST community may also choose to use the process
(particularly for Informational MEPs) to document expected syntax conventions and
to manage complex design coordination problems that require collaboration across
multiple projects.

## MEP Types

There are three kinds of MEP:

1. A **Standards Track** MEP describes a new syntax or AST element for MyST.

2. An **Informational** MEP describes a MyST design issue,
or provides general guidelines or information to the MyST community,
but does not propose a new feature.
Informational MEPs do not necessarily represent a MyST community consensus or recommendation,
so users and implementers are free to ignore Informational MEPs or follow their advice.

3. A **Process** MEP describes a process surrounding MyST, or proposes a change to (or an event in) a process.
Process MEPs are like Standards Track MEPs but apply to areas other than the MyST syntax itself.
They often require community consensus;
unlike Informational MEPs, 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 or environment used in MyST development.
Any meta-MEP is also considered a Process MEP.

## MEP Workflow

### MyST's Steering Council

There are several references in this MEP to the "Steering Council" or "Council".
This refers to the current members of the elected Steering Council described,
in their role as the final authorities on whether or not MEPs will be accepted or rejected.

### MyST's Core Developers

There are several references in this MEP to "core developers".
This refers to the currently active MyST core team members.

### MEP Editors

The MEP editors are individuals responsible for managing the administrative and editorial aspects of the MEP workflow
(e.g. assigning MEP numbers and changing their status).
See [MEP Editor Responsibilities & Workflow](mep-editor-responsibilities) for details.

MEP editorship is by invitation of the current editors, and they can be contacted by mentioning `@executablebooks/mep-editors` on GitHub.
All of the MEP workflow can be conducted via the GitHub [MEP repository] issues and pull requests.

### Start with an idea for MyST

The MEP process begins with a new idea for MyST.
It is highly recommended that a single MEP contain a single key proposal or new idea.
Small enhancements or patches often don't need a MEP and can be injected into the MyST development workflow with a submission to the [MyST specification] or tool.
The more focused the MEP, the more successful it tends to be.
The MEP editors reserve the right to reject MEP proposals if they appear too unfocused or too broad.
If in doubt, split your MEP into several well-focused ones.

Each MEP must have a champion --
someone who writes the MEP using the style and format described below, shepherds the discussions in the appropriate forums,
and attempts to build community consensus around the idea.
The MEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is MEP-able.
Posting to the [MEP discussions] is the best way to go about this.

Vetting an idea publicly before going as far as writing a MEP is meant to save the potential author time.
Many ideas have been brought forward for changing MyST that have been rejected for various reasons.
Asking the MyST 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.
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 will work for most people in most areas where MyST is used.

Once the champion has asked the MyST community as to whether an idea has any chance of acceptance,
a draft MEP should be presented in the discussion.
This gives the author a chance to flesh out the draft MEP to make properly formatted, of high quality, and to address initial concerns about the proposal.

### Submitting an MEP

Following a discussion on [MEP discussions], the workflow varies based on whether any of the MEP's co-authors are core developers.
If one or more of the MEP's co-authors are core developers, they are responsible for following the process outlined below.
Otherwise (i.e. none of the co-authors are core developers), then the MEP author(s) will need to find a sponsor for the MEP.

Ideally, a core developer sponsor is identified, but non-core sponsors may also be selected, with the approval of the Steering Council.
The sponsor's job is to provide guidance to the MEP author to help them through the logistics of the MEP process (somewhat acting like a mentor).
Being a sponsor does **not** disqualify that person from becoming a co-author or MEP-Delegate later on (but not both).
The sponsor of a MEP is recorded in the "mep:sponsor:" field of the header.

Once the sponsor or the core developer(s) co-authoring the MEP deem the MEP ready for submission,
the proposal should be submitted as a draft MEP via a [GitHub pull request].
The draft must be written in MEP style as described below, else it will fail review immediately (although minor errors may be corrected by the editors).

The standard MEP workflow is:

- You, the MEP author, fork the [MEP repository], and create a file named `mep-9999.md` that contains your new MEP.
Use "9999" as your draft MEP number.

- In the "mep:type:" header field, enter "Standards Track", "Informational", or "Process" as appropriate,
and for the "mep:status:" field enter "Draft".
For full details, see [](mep-header-preamble).

- Update `.github/CODEOWNERS` [^codeowners] such that any core developer co-author(s) or sponsor are listed for your new file,
such that any future pull requests will be assigned to them.

- Push this to your GitHub fork and submit a pull request.

- The MEP editors review your PR for structure, formatting, and other errors.
Approval criteria are:

- It sound and complete.
The ideas must make technical sense.
The editors do not consider whether they seem likely to be accepted.
- The title accurately describes the content.
- The MEP's language (spelling, grammar, sentence structure, etc.) should be correct and conformant.

Editors are generally quite lenient about this initial review,
expecting that problems will be corrected by the reviewing process.

  Approval of the MEP is no guarantee that there are no embarrassing mistakes!
  Correctness is the responsibility of authors and reviewers, not the editors.

If the MEP isn't ready for approval, an editor will send it back to the author for revision, with specific instructions.

- Once approved, they will assign your MEP a number.

Once the review process is complete, and the MEP editors approve it (note that this is _not_ the same as accepting your MEP!),
they will squash commit your pull request onto `main`.

The MEP editors will not unreasonably deny publication of a MEP.
Reasons for denying MEP status include;
duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the MyST philosophy.
The Steering Council can be consulted during the approval phase, and are the final arbiter of a draft's MEP-ability.

Developers with git push privileges for the [MEP repository] may claim MEP numbers directly by creating and committing a new MEP.
When doing so, the developer must handle the tasks that would normally be taken care of by the MEP editors (see [MEP Editor Responsibilities & Workflow](mep-editor-responsibilities)).
This includes ensuring the initial version meets the expected standards for submitting a MEP.
Alternately, even developers should submit MEPs via pull request.
When doing so, you are generally expected to handle the process yourself; if you need assistance from MEP editors, mention `@executablebooks/mep-editors` on GitHub.

As updates are necessary, the MEP author can check in new versions if they (or a collaborating developer) have git push privileges.

After a MEP number has been assigned, a draft MEP may be discussed further on [MEP discussions]
(getting a MEP number assigned early can be useful for ease of reference, especially when multiple draft MEPs are being considered at the same time).

Standards Track MEPs consist of two parts, a design document and a reference implementation.
It is generally recommended that at least a prototype implementation be co-developed with the MEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation.

MEP authors are responsible for collecting community feedback on a MEP before submitting it for review.
However, wherever possible, long open-ended discussions on public forums should be avoided.
MEP authors should use their discretion here.

### MEP Review & Resolution

Once the authors have completed a MEP, they may request a review for style and consistency from the `@executablebooks/mep-editors`.

To expedite the process in selected cases (e.g. when a change is clearly beneficial and ready to be accepted, but the MEP hasn't been formally submitted for review yet),
the Steering Council may also initiate a MEP review, first notifying the MEP author(s) and giving them a chance to make revisions.

The final authority for MEP approval is the Steering Council.
However, whenever a new MEP is put forward, any core developer that believes they are suitably experienced to make the final decision on that MEP
may offer to serve as the MEP-Delegate for that MEP, and they will then have the authority to approve (or reject) that MEP.
Individuals taking on this responsibility are free to seek additional guidance from the Steering Council at any time,
and are also expected to take the advice and perspectives of other core developers into account.

The designated decision maker for each MEP is recorded in the "MEP-Delegate" header in the MEP.

Such self-nominations are accepted by default, but may be explicitly declined by the Steering Council.
Possible reasons for the Steering Council declining a self-nomination as MEP-Delegate include, but are not limited to, perceptions of a potential conflict of interest
(e.g. working for the same organisation as the MEP submitter),
or simply considering another potential MEP-Delegate to be more appropriate.
If core developers (or other community members) have concerns regarding the suitability of a MEP-Delegate for any given MEP,
they may ask the Steering Council to review the delegation.

If no volunteer steps forward, then the Steering Council will approach core developers (and potentially other MyST community members) with relevant expertise,
in an attempt to identify a candidate that is willing to serve as MEP-Delegate for that MEP.
If no suitable candidate can be found, then the MEP will be marked as Deferred until one is available.

Previously appointed MEP-Delegates may choose to step down, or be asked to step down by the Council,
in which case a new MEP-Delegate will be appointed in the same manner as for a new MEP (including deferral of the MEP if no suitable replacement can be found).
In the event that a MEP-Delegate is asked to step down, this will overrule any prior acceptance or rejection of the MEP, and it will revert to Draft status.

When such standing delegations are put in place, the Steering Council will maintain sufficient public records to allow subsequent Councils,
the core developers, and the wider MyST community to understand the delegations that currently exist,
why they were put in place, and the circumstances under which they may no longer be needed.

For a MEP to be accepted it must meet certain minimum criteria.
It must be a clear and complete description of the proposed enhancement.
The enhancement must represent a net improvement.
The proposed implementation, if applicable, must be solid and must not complicate the parsing unduly.

Once a MEP has been accepted, the reference implementation must be completed.
When the reference implementation is complete and incorporated into the [myst implementation], the status will be changed to "Final".

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

A MEP 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 MEP author themselves has decided that the MEP is actually a bad idea, or has accepted that a competing proposal is a better alternative.

When a MEP is Accepted, Rejected or Withdrawn, the MEP should be updated accordingly.
In addition to updating the status field, at the very least the Resolution header should be added with a link to the relevant post in the [mep discussions].

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

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

:alt: MEP process flow diagram

While not shown in the diagram, "Accepted" MEPs may technically move to "Rejected" or "Withdrawn" even after acceptance.
This will only occur if the implementation process reveals fundamental flaws in the design that were not noticed prior to acceptance of the MEP.
Unlike Provisional MEPs, these transitions are only permitted if the accepted proposal has _not_ been included in a Specification release -
released changes must instead go through the regular deprecation process (which may require a new MEP providing the rationale for the deprecation).

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

### MEP Maintenance

In general, Standards track MEPs are no longer modified after they have
reached the Final state. Once a MEP has been completed, the [myst spec] becomes the formal documentation of the expected behavior.

If changes based on implementation experience and user feedback are made to Standards track MEPs while in the Accepted or Provisional State,
those changes should be noted in the MEP, such that the MEP accurately describes the state of the implementation at the point where it is marked Final.

Informational and Process MEPs 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 MEP being updated.

## What belongs in a successful MEP?

Each MEP should have the following parts/sections:

1. Front matter -- A YAML front-matter block containing meta-data about the
MEP, under the `mep` key, including the MEP number (`id`), the names, and optionally the contact info for each author, etc.

2. Title -- a short descriptive title (limited to a maximum of 44 characters)

3. Abstract -- a short (~200 word) description of the technical issue being addressed.

4. Motivation -- The motivation is critical for MEPs that want to
change the MyST specification, or ecosystem.
It should clearly explain why the existing language specification is inadequate to address the problem that the MEP solves.
This can include collecting documented support for the MEP from important projects in the MyST ecosystem.
MEP submissions without sufficient motivation may be rejected.

5. Rationale -- The rationale fleshes out the specification by describing 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 syntaxes.

The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

6. Specification -- The technical specification should describe the syntax and semantics of any new feature.
The specification should be detailed enough to allow for interoperable implementations of the parser.

7. Backwards Compatibility -- All MEPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity.
The MEP must explain how the author proposes to deal with these incompatibilities. MEP submissions without a sufficient backwards compatibility treatise may be rejected outright.

9. How to Teach This -- For a MEP that adds new functionality or changes syntax behavior,
it is helpful to include a section on how to teach users, new and experienced, how to apply the MEP to their work.

This section may include key points and recommended documentation
changes that would help users adopt a new feature or migrate their
documentation to use a syntax change.

10. Reference Implementation -- The reference implementation must be
completed before any MEP is given status "Final", but it need not
be completed before the MEP is accepted.
While there is merit to the approach of reaching consensus on the specification and
rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of technical details.

The final implementation must include test fixtures and documentation appropriate the [myst spec].

11. Rejected Ideas -- Throughout the discussion of a MEP, various ideas
will be proposed which are not accepted.
Those rejected ideas should be recorded along with the reasoning as to why they were rejected.
This both helps record the thought process behind the final version of the MEP as well as preventing people from bringing up the same rejected idea again in subsequent discussions.

In a way this section can be thought of as a breakout section of the
Rationale section that is focused specifically on why certain ideas
were not ultimately pursued.

12. Open Issues -- While a MEP is in draft, ideas can come up which
warrant further discussion.
Those ideas should be recorded so people know that they are being thought about but do not have a concrete
resolution.
This helps make sure all issues required for the MEP to be ready for consideration are complete and reduces people duplicating prior discussion.

13. References -- A collection of URLs used as references through the MEP.

14. Copyright/license -- Each new MEP must be placed under a dual license of
public domain and [CC0-1.0-Universal] (see this MEP for an example).

## MEP Formats and Templates

MEPs are UTF-8 encoded text files using the MyST format.

The MEP text files are automatically converted to HTML [^mep-render] for easier online reading.

(mep-header-preamble)=
## MEP Header Preamble

Each MEP must begin with a YAML formatted front-matter section, with an `mep` key.

---
mep:
  # required
  id: <MEP number>
  created: <date created on, in dd-mmm-yyyy format>
  author:
  - <author's real names, optional github handle>
  type: <Standards Track | Informational | Process>
  status: <Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
  discussions-to: <URL of current canonical discussion thread>
  # optional
  sponsor: <sponsor's real name>
  mep-delegate: <MEP delegate's real name>
  requires: <MEP numbers>
  replaces: <MEP number>
  superseded-by: <MEP number>
---

The `author` field should be a string or list of the names and optionally the github handles of the authors/owners of the MEP, e.g.

author:
- Firstname Lastname (@githubhandle)
- Firstname Lastname (@githubhandle)

The `sponsor` field records which developer (core, or otherwise approved by the Steering Council) is sponsoring the MEP.
If one of the authors of the MEP is a core developer then no sponsor is necessary and thus this field should be left out.

The `mep-delegate` field is used to record the individual appointed by the Steering Council to make the final decision on whether or not to approve or reject a MEP.

The `type` field specifies the type of MEP: Standards Track, Informational, or Process.

The `created` field records the date that the MEP was assigned a number.

MEPs may have a `requires` field, indicating the MEP numbers that this MEP depends on.

MEPs may also have a `superseded-by` header indicating that a MEP has been rendered obsolete by a later document;
the value is the number of the MEP that replaces the current document.
The newer MEP must have a `replaces` header containing the number of the MEP that it rendered obsolete.

## Auxiliary Files

MEPs may include auxiliary files such as diagrams.
Such files should be placed in a subdirectory called `mep-XXXX`, where "XXXX" is the MEP number.

## Reporting MEP Bugs, or Submitting MEP Updates

How you report a bug, or submit a MEP update depends on several factors, such as the maturity of the MEP, the preferences of the MEP author, and the nature of your comments.
For the early draft stages of the MEP, it's probably best to send your comments and changes directly to the MEP author.
For more mature, or finished MEPs you may want to submit corrections as a [GitHub issue] or [GitHub pull request] so that your changes don't get lost.

When in doubt about where to send your changes, please check first with the MEP author and/or a MEP editor.

MEP authors with git push privileges for the MEP repository can update the MEPs themselves by using "git push" or the GitHub PR interface to submit their changes.

## Transferring MEP Ownership

It occasionally becomes necessary to transfer ownership of MEPs to a new champion.
In general, it is preferable to retain the original author as a co-author of the transferred MEP, but that's really up to the original author.
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 MEP process,
or 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 MEP.
One aim of the MEP process is to try to build consensus around a MEP, but if that's not possible, an author can always submit a competing MEP.

If you are interested in assuming ownership of a MEP, you can also do this via pull request.
Fork the [MEP repository], make your ownership modification, and submit a pull request.
You should mention both the original author and `@executablebooks/mep-editors` in a comment on the pull request.

(mep-editor-responsibilities)=

## MEP Editor Responsibilities & Workflow

A MEP editor must be added to the `@executablebooks/mep-editors` group on GitHub and must watch the [MEP repository].

Note that developers with git push privileges for the [MEP repository] may handle the tasks that would normally be taken care of by the MEP editors.
Alternately, even developers may request assistance from MEP editors by mentioning `@executablebooks/mep-editors` on GitHub.

For each new MEP that comes in an editor does the following:

- Make sure that the MEP is either co-authored by a core developer, has a core developer as a sponsor, or has a sponsor specifically approved for this MEP by the Steering Council.
- Read the MEP 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.
- The title should accurately describe the content.
- The file name extension is correct (i.e. `.md`).
- Make sure the appropriate core developer(s) is added to `.github/CODEOWNERS` [^codeowners].
- Skim the MEP for obvious defects in language (spelling, grammar,
sentence structure, etc.).
Editors may correct problems themselves, but are not required to do so.
- If a project is portrayed as benefiting from or supporting the MEP,
make sure there is some direct indication from the project included to make the support clear.
This is to avoid a MEP accidentally portraying a project as supporting a MEP when in fact the support is based on conjecture.

If the MEP isn't ready, an editor will send it back to the author for revision, with specific instructions.

Once the MEP is ready for the repository, a MEP editor will:

- Assign a MEP number (almost always just the next available number).
- Check that the author has correctly labeled the MEP's type
("Standards Track", "Informational", or "Process"), and marked its status as "Draft".
- Add the MEP to a local fork of the MEP repository.
- Check the PR CI passes.
- Commit and push the new (or updated) MEP

Updates to existing MEPs should be submitted as a [GitHub pull request].

MEP editors don't pass judgment on MEPs.
They merely do the administrative & editorial part (which is generally a low volume task).

## Copyright

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.

[mep repository]: https://github.com/executablebooks/myst-eps
[mep discussions]: https://github.com/executablebooks/myst-eps/discussions
[myst spec]: https://github.com/executablebooks/myst-spec
[myst implementation]: https://github.com/executablebooks/mystjs
[github pull request]: https://github.com/executablebooks/myst-eps/pulls
[github issue]: https://github.com/executablebooks/myst-eps/issues
[cc0-1.0-universal]: https://choosealicense.com/licenses/cc0-1.0/

[^history]: This historical record is available by the normal git commands for retrieving older revisions.

[^codeowners]: `CODEOWNERS` documentation (<https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners>)

[^mep-render]: More details on the MEP rendering and publication process can be found
in the MEPs repo README at: <https://github.com/executablebooks/myst-eps/blob/main/README.md>