<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title>Mallard Enhancement Proposals</title>
<link rel="stylesheet" type="text/css" href="http://projectmallard.org/C.css">
<script type="text/javascript" src="http://projectmallard.org/jquery.js"></script><script type="text/javascript" src="http://projectmallard.org/jquery.syntax.js"></script><script type="text/javascript" src="http://projectmallard.org/yelp.js"></script><link href="http://fonts.googleapis.com/css?family=Lato:400,700,900" rel="stylesheet" type="text/css">
</head>
<body>
<div class="top"><div class="content">
<a href="http://projectmallard.org/index.html"><img class="header-icon" width="80" height="80" src="http://projectmallard.org/mallard-logo-80.png"></a><div class="top-mallard"><a href="http://projectmallard.org/index.html">Mallard</a></div>
<div class="top-tagline"><a href="http://projectmallard.org/index.html">Better Help for Better Software</a></div>
</div></div>
<div class="page" role="main">
<div class="header"><div class="trails" role="navigation"><div class="trail">
<a class="trail" href="http://projectmallard.org/index.html">Mallard</a> » <a class="trail" href="http://projectmallard.org/mep/index.html" title="Mallard Enhancement Proposals">Proposals</a> » </div></div></div>
<div class="body">
<div class="hgroup">
<h1 class="title"><span class="title">MEP-0001</span></h1>
<h2 class="subtitle"><span class="subtitle">Mallard Enhancement Proposals</span></h2>
</div>
<div class="region">
<div class="contents">
<p class="p lead">This page outlines the process of proposing and evaluating
changes to Mallard and the core Mallard extensions.</p>
<div class="mep-info"><table>
<tr>
<th>Authors:</th>
<td>Shaun McCance</td>
</tr>
<tr>
<th>Created:</th>
<td>2013-08-17</td>
</tr>
<tr>
<th>Status:</th>
<td>proposed (2013-08-17)</td>
</tr>
<tr>
<th>History:</th>
<td class="pmo-mep-history"><div class="table ui-expander">
<div class="yelp-data yelp-data-ui-expander" data-yelp-expanded="false">
<div class="yelp-title-collapsed">show history</div>
<div class="yelp-title-expanded">hide history</div>
</div>
<div class="inner">
<div class="title"><span class="title">history</span></div>
<div class="region"><div class="contents"><table><tr>
<td>2013-08-17</td>
<td>proposed</td>
<td></td>
</tr></table></div></div>
</div>
</div></td>
</tr>
</table></div>
<div role="navigation" class="links sectionlinks"><div class="inner"><div class="region"><ul>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#background" title="Background">Background</a></li>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#proposal" title="Proposal">Proposal</a></li>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#template" title="Template">Template</a></li>
</ul></div></div></div>
</div>
<div id="background" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Background</span></h2></div>
<div class="region"><div class="contents">
<p class="p">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.</p>
<p class="p">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.</p>
<p class="p">There are three goals for this proposed process:</p>
<div class="list"><div class="inner"><div class="region"><ul class="list">
<li class="list"><p class="p">Allow people to participate in the development of Mallard without
requiring them to write full specifications, develop schemas, or implement
features in processing tools.</p></li>
<li class="list"><p class="p">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.</p></li>
<li class="list"><p class="p">Provide a historical record for the design decisions that led to
features in Mallard and core Mallard extensions.</p></li>
</ul></div></div></div>
</div></div>
</div></div>
<div id="proposal" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Proposal</span></h2></div>
<div class="region">
<div class="contents">
<p class="p">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.</p>
<div role="navigation" class="links sectionlinks"><div class="inner"><div class="region"><ul>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#proposing" title="Proposing">Proposing</a></li>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#status" title="Revisions and Status">Revisions and Status</a></li>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#info" title="Info and Introduction">Info and Introduction</a></li>
<li class="links "><a href="http://projectmallard.org/mep/mep0001.html#sections" title="Sections">Sections</a></li>
</ul></div></div></div>
</div>
<div id="proposing" class="sect"><div class="inner">
<div class="hgroup"><h3 class="title"><span class="title">Proposing</span></h3></div>
<div class="region"><div class="contents">
<p class="p">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
<span class="link"><a href="http://projectmallard.org/mailman/listinfo/mallard-list" title="http://projectmallard.org/mailman/listinfo/mallard-list">mallard-list</a></span>.
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.</p>
<p class="p">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.</p>
<p class="p">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.</p>
</div></div>
</div></div>
<div id="status" class="sect"><div class="inner">
<div class="hgroup"><h3 class="title"><span class="title">Revisions and Status</span></h3></div>
<div class="region"><div class="contents">
<p class="p">Each proposal should have at least one <span class="code">revision</span> element, and
each <span class="code">revision</span> element should have a <span class="code">date</span> attribute
and a <span class="code">status</span> attribute. You should add a <span class="code">revision</span>
element each time you change the status or make a substantive revision. Do
not remove or change previous <span class="code">revision</span> elements, unless they
were incorrect to begin with.</p>
<p class="p">The current revision is the <span class="code">revision</span> element with the latest
date. If there are multiple <span class="code">revision</span> elements that share the
latest date, the current revision is the last of these in document order.</p>
<p class="p">If the proposal is targeted for a specification, record that using the
<span class="code">docversion</span> attribute on the <span class="code">revision</span> element. Use
the <span class="link"><a href="http://projectmallard.org/1.0/mal_attr_version.html" title="Mallard Version">version</a></span> token as the attribute
value. If there are multiple affected specifications, use a space-separated
list of version tokens. The current target is the <span class="code">docversion</span>
attribute (if it exists) of the current revision.</p>
<p class="p">The current status of the proposal is the <span class="code">status</span> attribute
of the current revision. A proposal moves through the following statuses:</p>
<div class="terms"><div class="inner"><div class="region"><dl class="terms">
<dt class="terms">incomplete</dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms">proposed</dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms">revised</dt>
<dd class="terms"><p class="p">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 <span class="code">desc</span> element
that briefly describes the change and links to any online discussion of the
change.</p></dd>
<dt class="terms">implemented</dt>
<dd class="terms">
<p class="p">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.</p>
<p class="p">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.</p>
</dd>
<dt class="terms">final</dt>
<dd class="terms"><p class="p">The specification including the proposed behavior has been marked final,
and a complete reference implementation exists.</p></dd>
<dt class="terms">rejected</dt>
<dd class="terms"><p class="p">The proposal was rejected by the maintainers of the target specification.
A revision with the rejected status should include a <span class="code">desc</span> element
that briefly describes why the proposal was rejected and links to any online
discussion of the rejection.</p></dd>
<dt class="terms">replaced</dt>
<dd class="terms"><p class="p">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 <span class="code">desc</span> element that links to the replacement
proposal.</p></dd>
<dt class="terms">withdrawn</dt>
<dd class="terms"><p class="p">The proposal was withdrawn by the authors. A revision with the withdrawn
status should include a <span class="code">desc</span> element that briefly describes why
the proposal with withdrawn and links to any online discussion of the
withdrawal.</p></dd>
</dl></div></div></div>
</div></div>
</div></div>
<div id="info" class="sect"><div class="inner">
<div class="hgroup"><h3 class="title"><span class="title">Info and Introduction</span></h3></div>
<div class="region"><div class="contents">
<p class="p">All authors and copyright holders must be properly credited with the
<span class="code">credit</span> 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.</p>
<div class="listing"><div class="inner">
<div class="title title-listing"><h4><span class="title"><span class="file">cc-by-sa-3-0.xml</span></span></h4></div>
<div class="region"><div class="contents"><div class="code"><pre class="contents syntax brush-html"><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></pre></div></div></div>
</div></div>
<p class="p">If a proposal depends on another proposal that is still under
development, record that as an informational link to the other proposal
with the <span class="code">type</span> attribute set to <span class="code">"mep:depends"</span>.
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 <span class="code">type</span> attribute set to
<span class="code">"mep:replaces"</span>. If another proposal is interesting in
any other way, record that as a <span class="code">"seealso"</span> link.</p>
<p class="p">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
<span class="code">desc</span> element with a brief synopsis of the proposal, and
include a lead paragraph that states the intent of the proposal.</p>
</div></div>
</div></div>
<div id="sections" class="sect"><div class="inner">
<div class="hgroup"><h3 class="title"><span class="title">Sections</span></h3></div>
<div class="region"><div class="contents"><div class="terms"><div class="inner"><div class="region"><dl class="terms">
<dt class="terms"><span class="em-bold em">Background</span></dt>
<dd class="terms"><p class="p">Describe the problems and situations that have led up to this proposal,
as well as any goals this proposal should be evaluated against.</p></dd>
<dt class="terms"><span class="em-bold em">Proposal</span></dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms"><span class="em-bold em">Addendums</span></dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms"><span class="em-bold em">Examples</span></dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms"><span class="em-bold em">Accessibility</span></dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms"><span class="em-bold em">Internationalization</span></dt>
<dd class="terms"><p class="p">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.</p></dd>
<dt class="terms"><span class="em-bold em">Alternatives</span></dt>
<dd class="terms"><p class="p">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. If no alternatives were considered,
explain why.</p></dd>
<dt class="terms"><span class="em-bold em">Compatibility and Fallback</span></dt>
<dd class="terms">
<p class="p">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.</p>
<p class="p">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.</p>
<p class="p">Omit this section for process proposals.</p>
</dd>
<dt class="terms"><span class="em-bold em">Comparison to Other Formats</span></dt>
<dd class="terms">
<p class="p">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.</p>
<p class="p">Omit this section for process proposals.</p>
</dd>
</dl></div></div></div></div></div>
</div></div>
</div>
</div></div>
<div id="template" class="sect"><div class="inner">
<div class="hgroup"><h2 class="title"><span class="title">Template</span></h2></div>
<div class="region"><div class="contents"><div class="code"><pre class="contents syntax brush-html"><page xmlns="http://projectmallard.org/1.0/"
type="topic"
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"/>
-->
<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"/>
<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>
<!--
<section id="addendums">
<title>Addendums</title>
</section>
-->
<section id="examples">
<title>Examples</title>
</section>
<section id="a11y">
<title>Accessibility</title>
</section>
<section id="i18n">
<title>Internationalization</title>
</section>
<section id="alternatives">
<title>Alternatives</title>
</section>
<section id="compatibility">
<title>Compatibility and Fallback</title>
</section>
<section id="comparison">
<title>Comparison to Other Formats</title>
</section>
</page></pre></div></div></div>
</div></div>
<div class="sect sect-links" role="navigation">
<div class="hgroup"></div>
<div class="contents"><div class="links guidelinks"><div class="inner">
<div class="title"><h2><span class="title">More Information</span></h2></div>
<div class="region"><ul><li class="links "><a href="http://projectmallard.org/mep/index.html" title="Mallard Enhancement Proposals">Mallard Enhancement Proposals</a></li></ul></div>
</div></div></div>
</div>
</div>
<div class="clear"></div>
</div>
<div class="footer"></div>
</div>
<div class="bottom"><div class="content">
<div class="bottom-badge"><div>© 2013 Shaun McCance</div></div>
<div class="bottom-badge ui-expander">
<div class="yelp-data yelp-data-ui-expander" data-yelp-expanded="false"></div>
<div class="inner">
<div class="hgroup">cc-by-sa 3.0 (us)</div>
<div class="region"><div class="contents">
<p class="p">This work is licensed under a
<span class="link"><a href="http://creativecommons.org/licenses/by-sa/3.0/us/" title="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative Commons
Attribution-Share Alike 3.0 United States License</a></span>.</p>
<p class="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>
</div></div>
</div>
</div>
<div class="bottom-badge">
<div>Powered by </div>
<a href="http://projectmallard.org"><img alt="Mallard" width="80" height="15" src="http://projectmallard.org/mallard-badge.png"></a>
</div>
<div class="bottom-badge">Hosted by <a href="http://syllogist.net/">Syllogist</a>
</div>
</div></div>
</body>
</html>