MEP-0001

Mallard Enhancement Proposals

This page outlines the process of proposing and evaluating changes to Mallard and the core Mallard extensions.

Authors:

Shaun McCance

Created:

2013-08-17

Status:

proposed (2013-08-17)

History:

show history

hide history

history

2013-08-17

proposed

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.

Background

Mallard is developed by an open source community. Often, an idea for a Mallard feature or extension will come about during a doc sprint or design session. This will get added to somebody's private TODO list and possibly implemented in an experimental namespace. As the problem space becomes more clear, the feature will change until a specification written is finalized.

This process does a poor job of recording the problems, the ideas for solving those problems, the community input, and the design changes that lead up to the final specification.

There are three goals for this proposed process:

Allow people to participate in the development of Mallard without requiring them to write full specifications, develop schemas, or implement features in processing tools.
Record the current state of experimental features that do not yet have a formal specification, allowing people to use these features and provide feedback on them.
Provide a historical record for the design decisions that led to features in Mallard and core Mallard extensions.

Proposal

A Mallard Enhancement Proposal (MEP) is a page that records the rationale and design of a Mallard feature or extension. MEPs are modeled after similar documents used by other projects, most notably Python. A MEP is a Mallard page file hosted on projectmallard.org alongside other MEPs.

Proposing

To propose a large change to Mallard or to a core extension, to propose a new extension to be hosted on projectmallard.org, or to propose a change in the process for developing Mallard and core Mallard extensions, write a Mallard Enhancement Proposal following the format outlined in this proposal. Send the proposal to mallard-list. If accepted as a proposal, it will be assigned a number and added to the projectmallard git repository. Acceptance as a proposal does not imply that the proposed functionality or process will be approved.

You may submit an incomplete proposal, or even a page that does not yet make a concrete proposal and just outlines a problem to solve. After the proposal is accepted, the authors of the proposal are responsible for driving discussion, addressing the concerns of the community, and convincing the community that the proposal should be implemented. The authors of the proposal are not necessarily responsible for implementing the proposed functionality, but they are responsible for convincing others to implement it.

For proposals that target existing specifications, the final decision rests with the maintainers of those specifications. Proposals for a new specification require somebody to volunteer to write and maintain the specification.

Revisions and Status

Each proposal should have at least one revision element, and each revision element should have a date attribute and a status attribute. You should add a revision element each time you change the status or make a substantive revision. Do not remove or change previous revision elements, unless they were incorrect to begin with.

The current revision is the revision element with the latest date. If there are multiple revision elements that share the latest date, the current revision is the last of these in document order.

If the proposal is targeted for a specification, record that using the docversion attribute on the revision element. Use the version token as the attribute value. If there are multiple affected specifications, use a space-separated list of version tokens. The current target is the docversion attribute (if it exists) of the current revision.

The current status of the proposal is the status attribute of the current revision. A proposal moves through the following statuses:

incomplete

The page does not yet make a concrete proposal. Pages without proposals may be accepted as proposals if they outline a real problem and there is clear intent to gather information and make a proposal.

proposed

The page makes a concrete proposal on how to solve a problem. It may not have all non-normative sections completed, such as comparisons to other formats or impact on accessibility or internationalization.

revised

A substantive revision was made to an existing proposal. A proposal may be revised any number of times, and each is recorded with this status. A revision with the revised status should include a desc element that briefly describes the change and links to any online discussion of the change.

implemented

All sections of the proposal have been completed, a specification has been written and is hosted on projectmallard.org, and the behavior has been implemented in a reference implementation. The specification may still be incomplete in non-normative sections, such as examples or comparisons to other formats. The reference implementation may use a temporary experimental namespace instead of the final namespace used by the specification.

If a substantive revision is made after a proposal is marked implemented, it must include a revision marking it revised before being marked implemented again. Both revisions may be added in a single commit.

final

The specification including the proposed behavior has been marked final, and a complete reference implementation exists.

rejected

The proposal was rejected by the maintainers of the target specification. A revision with the rejected status should include a desc element that briefly describes why the proposal was rejected and links to any online discussion of the rejection.

replaced

The proposal was rejected or withdrawn in favor of another proposal that addresses a similar set of problems. A revision with the replaced status should include a desc element that links to the replacement proposal.

withdrawn

The proposal was withdrawn by the authors. A revision with the withdrawn status should include a desc element that briefly describes why the proposal with withdrawn and links to any online discussion of the withdrawal.

Info and Introduction

All authors and copyright holders must be properly credited with the credit element, including email addresses and copyright years. The proposal must be licensed under the currently preferred open license for specifications on projectmallard.org. At the time of this proposal, that is the Creative Commons Attribution-ShareAlike US 3.0, with a special exception for example code.

cc-by-sa-3-0.xml

<license xmlns="http://projectmallard.org/1.0/"
         href="http://creativecommons.org/licenses/by-sa/3.0/us/">
<p>This work is licensed under a
<link href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative Commons
Attribution-Share Alike 3.0 United States License</link>.</p>
<p>As a special exception, the copyright holders give you permission to copy,
modify, and distribute the example code contained in this document under the
terms of your choosing, without restriction.</p>
</license>

If a proposal depends on another proposal that is still under development, record that as an informational link to the other proposal with the type attribute set to "mep:depends". Do not record dependencies to proposals that are already final at the time of proposal. If a proposal replaces another proposal, record that as an informational link with the type attribute set to "mep:replaces". If another proposal is interesting in any other way, record that as a "seealso" link.

Set the primary title to the MEP identifier (“MEP-0001” for this proposal), and the subtitle to the MEP title (“Mallard Enhancement Proposals” for this proposal). Set the link title to the MEP identifier and the MEP title joined with a colon (“MEP-0001: Mallard Enhancement Proposals”), and the text title to just the MEP title. Include a desc element with a brief synopsis of the proposal, and include a lead paragraph that states the intent of the proposal.

Sections

Background

Describe the problems and situations that have led up to this proposal, as well as any goals this proposal should be evaluated against.

Proposal

Describe the proposal in detail, accounting for all changes to schemas and processing expectations. Be specific, but assume the reader is already very familiar with Mallard and any referenced extensions or technologies.

Addendums

Once a proposal has been marked final, the main proposal should be left alone for historical reference. If a small change is made after the proposal has been marked final, it should be noted in this section. If a large change is made, it should have its own MEP, and that MEP should be linked to from this section. Only add this section when addendums are made.

Examples

Provide examples that illustrate the proposed functionality. For each example, show the markup and explain the expected behavior. Try to make the examples illustrative of real-world needs that are addressed by this proposal.

Accessibility

If the proposal has an impact on the accessibility of pages to users of assistive technologies, note that impact in its own section. You may omit this section if there is no accessibility impact.

Internationalization

If the proposal has an impact on the internationalization or localization of pages, note that impact in its own section. You may omit this section if there is no internationalization impact.

Alternatives

Describe any alternatives that were also considered to solve the same problems. Update this section throughout the proposal process to include any additional alternatives that arise, including proposals made in previous revisions of the proposal. You may omit this section if no alternatives were considered.

Compatibility and Fallback

Explain any backwards incompatibilities in detail. For this purpose, an incompatibility is any issue that arises when a page that was not written with this proposal in mind is processed by a tool that supports this proposal. Incompatibilities should be avoided. If they exist, explain the impact and why you feel it's acceptable.

Also explain the fallback behavior of this proposal. Mallard defines fallback behavior for unrecognized elements in various contexts. Proposals should try to take advantage of these behaviors so that pages that use the proposal have a reasonable presentation with non-supporting tools. If this is not possible, explain why.

Omit this section for process proposals.

Comparison to Other Formats

Describe any similar elements or behaviors from comparable formats, such as DocBook, DITA, or XHTML. It is sometimes worthwhile to reuse behavior from other formats. Explain any interesting differences and similarities.

Omit this section for process proposals.

Template

<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="mep"
      id="mepXXXX">

<info>
  <link type="guide" xref="index" group="TARGET"/>

  <!--
  <link type="mep:depends" xref="mepYYYY"/>
  <link type="mep:replaces" xref="mepYYYY"/>
  <link type="seealso" xref="mepYYYY"/>
  <link type="mep:issue" href="https://github.com/projectmallard/projectmallard.org/issues/XX">
    <title>Issue #XX</title>
  </link>
  -->

  <credit type="author copyright">
    <name>Author Name</name>
    <email>author.email@example.com</email>
    <years>YEARS</years>
  </credit>

  <include href="../cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  <!--
  list of valid status attributes:
  incomplete proposed revised implemented final rejected replaced withdrawn
  -->
  <revision date="DATE-PROPOSED" docversion="TARGET" status="proposed"/>

  <title type="text">PRIMARY TITLE</title>
  <title type="link">MEP-XXXX: PRIMARY TITLE</title>

  <desc>MEP DESCRIPTION</desc>
</info>

<title>MEP-XXXX</title>
<subtitle>PRIMARY TITLE</subtitle>

<p style="lead">This page outlines...</p>

<links type="section"/>

<section id="background">
  <title>Background</title>
</section>

<section id="proposal">
  <title>Proposal</title>
</section>

<!--
Add Addendums if changes are made after the proposal is final.
-->
<!--
<section id="addendums">
  <title>Addendums</title>
</section>
-->

<section id="examples">
  <title>Examples</title>
</section>

<!--
Omit Accessibility if there is no accessibility impact.
-->
<section id="a11y">
  <title>Accessibility</title>
</section>

<!--
Omit Internationalization if there is no internationalization impact.
-->
<section id="i18n">
  <title>Internationalization</title>
</section>

<!--
Omit Alternatives if no alternatives were considered.
-->
<section id="alternatives">
  <title>Alternatives</title>
</section>

<!--
Omit Compatibility and Fallback for process proposals.
-->
<section id="compatibility">
  <title>Compatibility and Fallback</title>
</section>

<!--
Omit Comparison to Other Formats for process proposals.
-->
<section id="comparison">
  <title>Comparison to Other Formats</title>
</section>

</page>