From 868d49cd74939b97e165fe5ec829ce0e4a3e2e8b Mon Sep 17 00:00:00 2001 From: Emmanuelle Delescolle Date: Mon, 7 Oct 2024 15:51:23 +0200 Subject: [PATCH 01/10] provide a .md template alongside the .rst one --- final/0001-dep-process.rst | 8 +-- template.md | 100 +++++++++++++++++++++++++++++++++++++ template.rst | 12 +---- 3 files changed, 107 insertions(+), 13 deletions(-) create mode 100644 template.md diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index 9b6ded7e..49c02233 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -295,11 +295,13 @@ DEP format To save everyone time reading DEPs, they need to follow a common format and outline; this section describes that format. In most cases, it's probably -easiest to start with copying the provided `DEP template <../template.rst>`_, +easiest to start with copying one of the provided DEP templates +(`rst template <../template.rst>` - `md template <../template.md>`)_, and filling it in as you go. -DEPs must be written in `reStructuredText `_ -(the same format as Django's documentation). +DEPs may be written in `reStructuredText `_ +(the same format as Django's documentation) or +`MarkDown ` (the same as GitHub issues). Each DEP should have the following parts: diff --git a/template.md b/template.md new file mode 100644 index 00000000..4e46fe69 --- /dev/null +++ b/template.md @@ -0,0 +1,100 @@ +--- +DEP: XXXX +Author: Jacob Kaplan-Moss +Implementation Team: Jacob Kaplan-Moss +Shepherd: Andrew Godwin, Carl Meyer +Status: Draft +Type: Feature +Created: 2014-11-16 +Last-Modified: 2014-11-18 +--- +# DEP XXXX: DEP template + +Table of Contents +- [Abstract](#abstract) +- [Specification](#specification) +- [Motivation](#motivation) +- [Rationale](#rationale) +- [Backwards Compatibility](#backwards-compatibility) +- [Reference Implementation](#reference-implementation) +- [Copyright](#copyright) + +This DEP provides a sample template for creating your own DEPs. In +conjunction with the content guidelines in [DEP +1](https://github.com/django/deps/final/0001-dep-process.rst), this +should make it easy for you to conform your own DEPs to the format +outlined below. + +Note: if you are reading this DEP via the web, you should first grab +[the source of this +DEP](https://raw.githubusercontent.com/django/deps/template.md) in +order to complete the steps below. **DO NOT USE THE HTML FILE AS YOUR +TEMPLATE!** + +To get the source this (or any) DEP, look at the top of the Github page +and click \"raw\". + +If you\'re unfamiliar with MarkDown, this template also exists +as a [reStructuredText template](./template.rst). + +Once you\'ve made a copy of this template, remove this abstract, fill +out the metadata above and the sections below, then submit the DEP. +Follow the guidelines in [DEP +1](https://github.com/django/deps/final/0001-dep-process.rst). + +## Abstract + +This should be a short (\~200 word) description of the technical issue +being addressed. + +This (and the above metadata) is the only section strictly required to +submit a draft DEP; the following sections can be barebones and fleshed +out as you work through the DEP process. + +## Specification + +This section should contain a complete, detailed technical specification +which should describe the syntax and semantics of any new feature. The +specification should be detailed enough to allow implementation \-- that +is, developers other than the author should (given the right experience) +be able to independently implement the feature, given only the DEP. + +## Motivation + +This section should explain *why* this DEP is needed. The motivation is +critical for DEPs that want to add substantial new features or +materially refactor existing ones. It should clearly explain why the +existing solutions are inadequate to address the problem that the DEP +solves. DEP submissions without sufficient motivation may be rejected +outright. + +## Rationale + +This section should flesh out out the specification by describing what +motivated the specific design and why particular design decisions were +made. It should describe alternate designs that were considered and +related work. + +The rationale should provide evidence of consensus within the community +and discuss important objections or concerns raised during discussion. + +## Backwards Compatibility + +If this DEP introduces backwards incompatibilities, you must must +include this section. It should describe these incompatibilities and +their severity, and what mitigation you plan to take to deal with these +incompatibilities. + +## Reference Implementation + +If there\'s an implementation of the feature under discussion in this +DEP, this section should include or link to that implementation and +provide any notes about installing/using/trying out the implementation. + +## Copyright + +This document has been placed in the public domain per the Creative +Commons CC0 1.0 Universal license +(). + +(All DEPs must include this exact copyright statement.) diff --git a/template.rst b/template.rst index 8116dd05..b07f075d 100644 --- a/template.rst +++ b/template.rst @@ -28,16 +28,8 @@ TEMPLATE!** To get the source this (or any) DEP, look at the top of the Github page and click "raw". -If you're unfamiliar with reStructuredText (the format required of DEPs), -see these resources: - -* `A ReStructuredText Primer`__, a gentle introduction. -* `Quick reStructuredText`__, a users' quick reference. -* `reStructuredText Markup Specification`__, the final authority. - -__ http://docutils.sourceforge.net/docs/rst/quickstart.html -__ http://docutils.sourceforge.net/docs/rst/quickref.html -__ http://docutils.sourceforge.net/spec/rst/reStructuredText.html +If you're unfamiliar with reStructuredText, this template also exists as a +`MarkDown template <./template.md>`_. Once you've made a copy of this template, remove this abstract, fill out the metadata above and the sections below, then submit the DEP. Follow the From 4282265ba359cf2c909cbfe8537e1cf32821c4c2 Mon Sep 17 00:00:00 2001 From: Emmanuelle Delescolle Date: Thu, 10 Oct 2024 10:43:24 +0200 Subject: [PATCH 02/10] fixed typo and wrong link Co-authored-by: Thibaud Colas --- final/0001-dep-process.rst | 2 +- template.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index 49c02233..548ba7a5 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -301,7 +301,7 @@ and filling it in as you go. DEPs may be written in `reStructuredText `_ (the same format as Django's documentation) or -`MarkDown ` (the same as GitHub issues). +`Markdown ` (the same as GitHub issues). Each DEP should have the following parts: diff --git a/template.md b/template.md index 4e46fe69..20f5200c 100644 --- a/template.md +++ b/template.md @@ -27,7 +27,7 @@ outlined below. Note: if you are reading this DEP via the web, you should first grab [the source of this -DEP](https://raw.githubusercontent.com/django/deps/template.md) in +DEP](https://raw.githubusercontent.com/django/deps/refs/heads/main/template.rst) in order to complete the steps below. **DO NOT USE THE HTML FILE AS YOUR TEMPLATE!** From 62e332511915b8727b29ccd825f0bbc9e5d8d45e Mon Sep 17 00:00:00 2001 From: Emmanuelle Delescolle Date: Thu, 10 Oct 2024 11:00:36 +0200 Subject: [PATCH 03/10] updated DEP 0001 preamble instructions --- final/0001-dep-process.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index 548ba7a5..aaa76845 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -308,10 +308,12 @@ Each DEP should have the following parts: #. A short descriptive title (e.g. "ORM expressions"), which is also reflected in the DEP's filename (e.g. ``0181-orm-expressions.rst``). -#. A preamble -- a rST `field list `_ - 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. +#. A preamble -- 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. + This can be provided as a rST `field list `_ + or MarkDown frontmatter `https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md`_ + depending on which temaplte you are using. #. Abstract -- a short (~200 word) description of the technical issue being addressed. From 9b45d16d83ea94615200d86273bc5e91a3efb5cc Mon Sep 17 00:00:00 2001 From: Emmanuelle Delescolle Date: Thu, 10 Oct 2024 11:13:55 +0200 Subject: [PATCH 04/10] Update template.md Co-authored-by: Thibaud Colas --- template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/template.md b/template.md index 20f5200c..8e137e70 100644 --- a/template.md +++ b/template.md @@ -21,7 +21,7 @@ Table of Contents This DEP provides a sample template for creating your own DEPs. In conjunction with the content guidelines in [DEP -1](https://github.com/django/deps/final/0001-dep-process.rst), this +1](https://github.com/django/deps/blob/main/final/0001-dep-process.rst), this should make it easy for you to conform your own DEPs to the format outlined below. From 172c3491bc3a61c599c6bcb1e811a1713b985283 Mon Sep 17 00:00:00 2001 From: Emmanuelle Delescolle Date: Mon, 6 Jan 2025 19:15:21 +0100 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Gert Van Gool --- final/0001-dep-process.rst | 6 +++--- template.md | 4 ++-- template.rst | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index aaa76845..4c001f74 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -301,7 +301,7 @@ and filling it in as you go. DEPs may be written in `reStructuredText `_ (the same format as Django's documentation) or -`Markdown ` (the same as GitHub issues). +`Markdown `_ (the same as GitHub issues). Each DEP should have the following parts: @@ -312,8 +312,8 @@ Each DEP should have the following parts: the names of the various members of the `DEP team <#forming- the-team>`_, and so forth. See `DEP Metadata`_ below for specific details. This can be provided as a rST `field list `_ - or MarkDown frontmatter `https://github.com/Kernix13/markdown-cheatsheet/blob/master/frontmatter.md`_ - depending on which temaplte you are using. + or `Markdown frontmatter `_ + depending on which template you are using. #. Abstract -- a short (~200 word) description of the technical issue being addressed. diff --git a/template.md b/template.md index 8e137e70..1efc0a52 100644 --- a/template.md +++ b/template.md @@ -27,14 +27,14 @@ outlined below. Note: if you are reading this DEP via the web, you should first grab [the source of this -DEP](https://raw.githubusercontent.com/django/deps/refs/heads/main/template.rst) in +DEP](https://raw.githubusercontent.com/django/deps/refs/heads/main/template.md) in order to complete the steps below. **DO NOT USE THE HTML FILE AS YOUR TEMPLATE!** To get the source this (or any) DEP, look at the top of the Github page and click \"raw\". -If you\'re unfamiliar with MarkDown, this template also exists +If you\'re unfamiliar with Markdown, this template also exists as a [reStructuredText template](./template.rst). Once you\'ve made a copy of this template, remove this abstract, fill diff --git a/template.rst b/template.rst index b07f075d..dda5fdba 100644 --- a/template.rst +++ b/template.rst @@ -29,7 +29,7 @@ To get the source this (or any) DEP, look at the top of the Github page and click "raw". If you're unfamiliar with reStructuredText, this template also exists as a -`MarkDown template <./template.md>`_. +`Markdown template <./template.md>`_. Once you've made a copy of this template, remove this abstract, fill out the metadata above and the sections below, then submit the DEP. Follow the From 26de2d75a3495f8df0b838b6f5ec9f24bda61435 Mon Sep 17 00:00:00 2001 From: Emmanuelle Delescolle Date: Tue, 14 Jan 2025 08:02:02 +0100 Subject: [PATCH 06/10] Stripped trailing space to match #64 --- final/0001-dep-process.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index 4c001f74..59a34a60 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -297,11 +297,11 @@ To save everyone time reading DEPs, they need to follow a common format and outline; this section describes that format. In most cases, it's probably easiest to start with copying one of the provided DEP templates (`rst template <../template.rst>` - `md template <../template.md>`)_, -and filling it in as you go. +and filling it in as you go. -DEPs may be written in `reStructuredText `_ +DEPs may be written in `reStructuredText `_ (the same format as Django's documentation) or -`Markdown `_ (the same as GitHub issues). +`Markdown `_ (the same as GitHub issues). Each DEP should have the following parts: From 61d6bfc60709dabfd9e79e3836cb744b2071f6a8 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Tue, 14 Jan 2025 08:24:22 +0100 Subject: [PATCH 07/10] Update final/0001-dep-process.rst Co-authored-by: Lily Foote --- final/0001-dep-process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index bc7d7acf..ad6c2bf2 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -295,7 +295,7 @@ DEP format To save everyone time reading DEPs, they need to follow a common format and outline; this section describes that format. In most cases, it's probably easiest to start with copying one of the provided DEP templates -(`rst template <../template.rst>` - `md template <../template.md>`)_, +(`rst template <../template.rst>`_ - `md template <../template.md>`_), and filling it in as you go. DEPs may be written in `reStructuredText `_ From 41992ebc0e35dbf458690695d7a3a3de8cd29ab5 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Tue, 14 Jan 2025 08:25:11 +0100 Subject: [PATCH 08/10] Update final/0001-dep-process.rst Co-authored-by: Lily Foote --- final/0001-dep-process.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/final/0001-dep-process.rst b/final/0001-dep-process.rst index ad6c2bf2..0e9a1f3a 100644 --- a/final/0001-dep-process.rst +++ b/final/0001-dep-process.rst @@ -311,8 +311,7 @@ Each DEP should have the following parts: the names of the various members of the `DEP team <#forming- the-team>`_, and so forth. See `DEP Metadata`_ below for specific details. This can be provided as a rST `field list `_ - or `Markdown frontmatter `_ - depending on which template you are using. + or `Markdown frontmatter `_. #. Abstract -- a short (~200 word) description of the technical issue being addressed. From a9395cda0976eab9f28459c55af62340518ff828 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Tue, 14 Jan 2025 08:27:43 +0100 Subject: [PATCH 09/10] Removed unnecessary escaping. --- template.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/template.md b/template.md index 1efc0a52..0a3f75f2 100644 --- a/template.md +++ b/template.md @@ -32,19 +32,19 @@ order to complete the steps below. **DO NOT USE THE HTML FILE AS YOUR TEMPLATE!** To get the source this (or any) DEP, look at the top of the Github page -and click \"raw\". +and click "raw". -If you\'re unfamiliar with Markdown, this template also exists +If you're unfamiliar with Markdown, this template also exists as a [reStructuredText template](./template.rst). -Once you\'ve made a copy of this template, remove this abstract, fill +Once you've made a copy of this template, remove this abstract, fill out the metadata above and the sections below, then submit the DEP. Follow the guidelines in [DEP 1](https://github.com/django/deps/final/0001-dep-process.rst). ## Abstract -This should be a short (\~200 word) description of the technical issue +This should be a short (~200 word) description of the technical issue being addressed. This (and the above metadata) is the only section strictly required to @@ -55,7 +55,7 @@ out as you work through the DEP process. This section should contain a complete, detailed technical specification which should describe the syntax and semantics of any new feature. The -specification should be detailed enough to allow implementation \-- that +specification should be detailed enough to allow implementation -- that is, developers other than the author should (given the right experience) be able to independently implement the feature, given only the DEP. @@ -87,7 +87,7 @@ incompatibilities. ## Reference Implementation -If there\'s an implementation of the feature under discussion in this +If there's an implementation of the feature under discussion in this DEP, this section should include or link to that implementation and provide any notes about installing/using/trying out the implementation. From 3fd2b1005917275d065ce08f3efc8ab93036b096 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Tue, 14 Jan 2025 11:03:58 +0100 Subject: [PATCH 10/10] Update template.rst --- template.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/template.rst b/template.rst index af5ff159..ada6cc2d 100644 --- a/template.rst +++ b/template.rst @@ -27,8 +27,19 @@ TEMPLATE!** To get the source this (or any) DEP, look at the top of the Github page and click "raw". -If you're unfamiliar with reStructuredText, this template also exists as a -`Markdown template <./template.md>`_. +This template uses reStructuredText. A `Markdown version<./template.md>`_ is +also available. + +These resources are a good place to start if you are unfamiliar with +reStructuredText: + + * `A ReStructuredText Primer`__, a gentle introduction. + * `Quick reStructuredText`__, a users' quick reference. + * `reStructuredText Markup Specification`__, the final authority. + + __ http://docutils.sourceforge.net/docs/rst/quickstart.html + __ http://docutils.sourceforge.net/docs/rst/quickref.html + __ http://docutils.sourceforge.net/spec/rst/reStructuredText.html Once you've made a copy of this template, remove this abstract, fill out the metadata above and the sections below, then submit the DEP. Follow the