Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
thibaudcolas opened this issue Dec 19, 2023 · 2 comments
Open

Comments

@thibaudcolas
Copy link
Member

thibaudcolas commented Dec 19, 2023

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
Copy link
Member

+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
Copy link
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants