mRFC 0001: Midgard Specification Process
This document outlines the Midgard Request For Comments (mRFC) procedure used for developing the Midgard Project. This mRFC been submitted to the Midgard Community for discussion and approval under the Creative Commons Attribution-ShareAlike license.
The primary reason for proposing the mRFC procedure is the fact, that there are often many ideas around, some get discussed on developer mailing list, some others even make it into CVS, some others don't even make them out of IRC or some developers brain. The mRFC procedure aims to implement a clear and documented policy for publishing, approval and implementation of these ideas.
Formatting and publication
The Midgard RFCs are handled as XHTML documents published as Midgard Articles in the Developer area of the Midgard website. mRFCs are edited by a defined group of authors. Only they may make changes to the mRFC itself. All other Midgard Contributors can add comments to the mRFC as annotations.
The formatting in the mRFC must adhere to the Midgard Visual Guidelines.
Each mRFC must begin with the mRFC number and a meaningful title. The authors and their email addresses must be listed below the title.
Below the title and author listings, there must be a short explanation on the purpose of the mRFC and the following statement:
This mRFC has been submitted to the Midgard Community for discussion and approval under the Creative Commons Attribution-ShareAlike license.
The mRFC should list links to additional information, and definitions of terms used as their own H2 level subsections, with the definitions handled as XHTML definition lists.
After publication the mRFC must be announced on the Midgard developer mailing list.
Annotations
As the regular end-of-page comment system often breaks the context, especially in larger files (like Outlook default quotes), the Midgard Contributor can use the following strategy to add their comments directly at the place where they belong to.
Between two paragraphs, where you want to add a comment, place your comments into a XHTML div element with class "annotation" and put a heading consisting of a title along with your user name ("I find this incompatible (torben)") directly below it, as an H4 level header. After that, you can freely write your comments about this particular point within the mRFC. The div may contain any regular XHTML mark-up, including listings, pre-formatted text and paragraphs.
When editing the document using the MidCOM "Edit this page" functionality, the annotation element can be added by selecting "Annotation" in the formatting pulldown in editor toolbar.
Example:
Names should be clearer (nico)
This release should rather be named "beta" as it is
quite complete.
Answers to the comments by other users or the author can be
added directly below the closure of the div
element, following the same commenting guidelines.
These comments can then be considered and integrated into the mRFC by the author(s).
Approval
mRFCs must be approved by the Midgard Community before being implemented. The approval process is handled by a vote initiated by the mRFC author(s) on the midgard developer mailing list. The voting thread subject line must be prefixed with [vote] and the mRFC number.
Each Midgard Contributor can vote by replying to the voting thread with a +1 or -1. The total number is calculated from these replies. Once the total reaches +5 the mRFC is approved, and can be implemented. The voting will automatically close within 3 days of posting. If the mRFC has not gathered enough votes in that time, it is considered rejected.
The status of the mRFC should be marked in the article:
- Draft
- mRFC still being worked on. Annotations are accepted
- Proposed
- mRFC has entered voting on Midgard developer list and cannot be modified
- Accepted
- mRFC has passed voting and can be implemented
- Rejected
- mRFC has not passed voting
- Implemented
- The mRFC has been implemented into Midgard Project
If abuse of the voting system appears, the Midgard Community may start requiring valid PGP signature from Midgard Contributors participating in the vote. The PGP signature must match the fingerprint posted on "Who's Who in Midgard".
Implementation
All commits into the Midgard CVS repository related to a specific mRFC must mention this in the commit message ("Implementing authentication as outlined in mRFC 0025").
If there are multiple bugs or enhancement requests related to the mRFC in the Midgard Issue Tracker, a tracking bug should be opened using the mRFC number and title, and listing all these issues as dependencies.
If there are multiple bugs or enhancement requests related to the mRFC in the Midgard Issue Tracker, a tracking bug should be opened using the mRFC number and title, and listing all these issues as dependencies.
Definitions
The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be intepreted as described in RFC 2119.
- Midgard Community
- International group of Midgard Contributors
- Midgard Contributor
- Individual who has gotten contributions accepted into the Midgard project and has both a listing in the "Who's who in Midgard" web page and commit access to the Midgard CVS repository
References
IETF Internet-Draft guidelines