Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 53 additions & 10 deletions docs/internals/contributing/writing-code/submitting-patches.txt
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ requirements:
feature, the change should also contain documentation.

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

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

Non-trivial contributions
=========================
Contributions which require community feedback
==============================================

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

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

If you're not sure whether your contribution should be considered non-trivial,
ask on the ticket for opinions.
The Django Forum or django-developers mailing list
--------------------------------------------------

You can propose a change on the `Django Forum`_ or |django-developers| mailing
list. You should explain the need for the change, go into details of the
approach and discuss alternatives.

Please include a link to such discussions in your contributions.

Third party package
-------------------

Django does not accept experimental features. All features must follow our
:ref:`deprecation policy <internal-release-deprecation-policy>`. Hence, it can
take months or years for Django to iterate on an API design.

If you need user feedback on a public interface, it is better to create a
third-party package first. You can iterate on the public API much faster, while
also validating the need for the feature.

Once this package becomes stable and there are clear benefits of incorporating
aspects into Django core, starting a discussion on the `Django Forum`_ or
|django-developers| mailing list would be the next step.

Django Enhancement Proposal (DEP)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@django/steering-council I would love to have you add your thoughts to this PR as this would be the first time we mention DEPs in the contributing docs

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sarahboyce Thank you reviewing.
I have updated changes, and this is what it looks like now

Screenshot 2024-09-12 at 2 32 43 PM

I’m wondering if the list items are too wordy because we have some paragraphs within them, like in DEP, where we have about three. Is this okay, or should we consider making it more concise? I’m also thinking it might be better to make the list items more descriptive. What do you think?

---------------------------------

Similar to Python’s PEPs, Django has `Django Enhancement Proposals`_ or DEPs. A
DEP is a design document which provides information to the Django community, or
describes a new feature or process for Django. They provide concise technical
specifications of features, along with rationales. DEPs are also the primary
mechanism for proposing and collecting community input on major new features.

Before considering writing a DEP, it is recommended to first open a discussion
on the `Django Forum`_ or |django-developers| mailing list. This allows the
community to provide feedback and helps refine the proposal. Once the DEP is
ready the :ref:`Steering Council <steering-council>` votes on whether to accept
it.

Some examples of DEPs that have been approved and fully implemented:

* `DEP 181: ORM Expressions <https://github.com/django/deps/blob/main/final/0181-orm-expressions.rst>`_
* `DEP 182: Multiple Template Engines <https://github.com/django/deps/blob/main/final/0182-multiple-template-engines.rst>`_
* `DEP 201: Simplified routing syntax <https://github.com/django/deps/blob/main/final/0201-simplified-routing-syntax.rst>`_

.. _Django Forum: https://forum.djangoproject.com/
.. _Django Enhancement Proposals: https://github.com/django/deps

.. _deprecating-a-feature:

Expand Down
1 change: 1 addition & 0 deletions docs/spelling_wordlist
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ deduplicates
deduplication
deepcopy
deferrable
DEP
deprecations
deserialization
deserialize
Expand Down