Feature request: allow writing a DEP in Markdown as well as rST

[thibaudcolas]

Reflecting on #28 and my first draft DEP in #84 – I’d like the ability to write a DEP in Markdown, as Jacob suggested on the forum: Updating our DEP process / DEP 1. There are a few reasons for this:

1. It’s how I write all of my content on the Django Forum, which is where I’ll usually flesh out technical discussions before going for a DEP.
2. It’s how I write content in GitHub comments on issues and pull requests, which is also how I flesh out technical discussions before going for a DEP.

I believe it would greatly simplify drafting DEPs if people were able to write them in a language that they’re more familiar with than reStructuredText. It also creates a significant amount of friction if we have to always convert syntax between a forum post and a DEP. We don’t have to rewrite existing DEPs, they’re fine as-is in rST. We would need to:

1. Update DEP 1 to allow writing in Markdown
2. Agree on how to do the DEP’s metadata fields in Markdown – either a table (identical output to reStructuredText), or YAML frontmatter
3. Add a template for Markdown DEPs (same content, different formatting)

DEP 1 on format

Here is what DEP 1 has to say about format for reference:

DEPs must be written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ 
(the same format as Django's documentation). 

Each DEP should have the following parts:

[…]

#. A preamble -- a rST `field list <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#field-lists>`_ 
   containing metadata about the DEP, including the DEP number, the names of the
   various members of the `DEP team <#forming- the-team>`_, and so forth. See
   `DEP Metadata`_ below for specific details.

---

I’d also recommend dropping the requirement to hard-wrap lines at 80 characters for prose, for future Markdown and reStructuredText DEPs. It makes it harder to read content in the DEP’s source format, and creates silly diffs. If we want to retain specific line break guidelines, I would recommend Semantic Line Breaks.

[adamchainz]

+1 to markdown and a big +1 to semantic line breaks. Although I love rST, it is a little less flexible and certainly less familiar to the average dev than markdown. Constraining the use of rST to the documentation (where it shines) sounds fine to me.

[thibaudcolas]

So – does this change require a DEP? 😄 should I just make a PR? This was in the original list of proposed changes from @jacobian – it feels like a quick win compared to the other ones, can I make a PR already? I’d love to convert #84 to Markdown to try this out.