You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
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:
Agree on how to do the DEP’s metadata fields in Markdown – either a table (identical output to reStructuredText), or YAML frontmatter
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.
The text was updated successfully, but these errors were encountered:
+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.
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.
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:
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:
DEP 1 on format
Here is what DEP 1 has to say about format for reference:
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.
The text was updated successfully, but these errors were encountered: