Skip to content

Commit 438fc42

Browse files
mharyamsarahboyce
authored andcommitted
Expanded contributor docs on getting feedback from the wider community.
1 parent 0c81775 commit 438fc42

File tree

2 files changed

+54
-10
lines changed

2 files changed

+54
-10
lines changed

docs/internals/contributing/writing-code/submitting-patches.txt

Lines changed: 53 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ requirements:
114114
feature, the change should also contain documentation.
115115

116116
When you think your work is ready to be reviewed, send :doc:`a GitHub pull
117-
request <working-with-git>`.
117+
request <working-with-git>`.
118118
If you can't send a pull request for some reason, you can also use patches in
119119
Trac. When using this style, follow these guidelines.
120120

@@ -140,20 +140,63 @@ Regardless of the way you submit your work, follow these steps.
140140
.. _ticket tracker: https://code.djangoproject.com/
141141
.. _Development dashboard: https://dashboard.djangoproject.com/
142142

143-
Non-trivial contributions
144-
=========================
143+
Contributions which require community feedback
144+
==============================================
145145

146-
A "non-trivial" contribution is one that is more than a small bug fix. It's a
147-
change that introduces new Django functionality and makes some sort of design
148-
decision.
146+
A wider community discussion is required when a patch introduces new Django
147+
functionality and makes some sort of design decision. This is especially
148+
important if the approach involves a :ref:`deprecation <deprecating-a-feature>`
149+
or introduces breaking changes.
149150

150-
If you provide a non-trivial change, include evidence that alternatives have
151-
been discussed on the `Django Forum`_ or |django-developers| list.
151+
The following are different approaches for gaining feedback from the community.
152152

153-
If you're not sure whether your contribution should be considered non-trivial,
154-
ask on the ticket for opinions.
153+
The Django Forum or django-developers mailing list
154+
--------------------------------------------------
155+
156+
You can propose a change on the `Django Forum`_ or |django-developers| mailing
157+
list. You should explain the need for the change, go into details of the
158+
approach and discuss alternatives.
159+
160+
Please include a link to such discussions in your contributions.
161+
162+
Third party package
163+
-------------------
164+
165+
Django does not accept experimental features. All features must follow our
166+
:ref:`deprecation policy <internal-release-deprecation-policy>`. Hence, it can
167+
take months or years for Django to iterate on an API design.
168+
169+
If you need user feedback on a public interface, it is better to create a
170+
third-party package first. You can iterate on the public API much faster, while
171+
also validating the need for the feature.
172+
173+
Once this package becomes stable and there are clear benefits of incorporating
174+
aspects into Django core, starting a discussion on the `Django Forum`_ or
175+
|django-developers| mailing list would be the next step.
176+
177+
Django Enhancement Proposal (DEP)
178+
---------------------------------
179+
180+
Similar to Python’s PEPs, Django has `Django Enhancement Proposals`_ or DEPs. A
181+
DEP is a design document which provides information to the Django community, or
182+
describes a new feature or process for Django. They provide concise technical
183+
specifications of features, along with rationales. DEPs are also the primary
184+
mechanism for proposing and collecting community input on major new features.
185+
186+
Before considering writing a DEP, it is recommended to first open a discussion
187+
on the `Django Forum`_ or |django-developers| mailing list. This allows the
188+
community to provide feedback and helps refine the proposal. Once the DEP is
189+
ready the :ref:`Steering Council <steering-council>` votes on whether to accept
190+
it.
191+
192+
Some examples of DEPs that have been approved and fully implemented:
193+
194+
* `DEP 181: ORM Expressions <https://github.com/django/deps/blob/main/final/0181-orm-expressions.rst>`_
195+
* `DEP 182: Multiple Template Engines <https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst>`_
196+
* `DEP 201: Simplified routing syntax <https://github.com/django/deps/blob/main/final/0201-simplified-routing-syntax.rst>`_
155197

156198
.. _Django Forum: https://forum.djangoproject.com/
199+
.. _Django Enhancement Proposals: https://github.com/django/deps
157200

158201
.. _deprecating-a-feature:
159202

docs/spelling_wordlist

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,7 @@ deduplicates
123123
deduplication
124124
deepcopy
125125
deferrable
126+
DEP
126127
deprecations
127128
deserialization
128129
deserialize

0 commit comments

Comments
 (0)