diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index cac6848d04..799292e3fd 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -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 `. +request `. 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. @@ -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 ` +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 `. 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) +--------------------------------- + +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 ` votes on whether to accept +it. + +Some examples of DEPs that have been approved and fully implemented: + +* `DEP 181: ORM Expressions `_ +* `DEP 182: Multiple Template Engines `_ +* `DEP 201: Simplified routing syntax `_ .. _Django Forum: https://forum.djangoproject.com/ +.. _Django Enhancement Proposals: https://github.com/django/deps .. _deprecating-a-feature: diff --git a/docs/spelling_wordlist b/docs/spelling_wordlist index d30f2ce440..747a712a62 100644 --- a/docs/spelling_wordlist +++ b/docs/spelling_wordlist @@ -123,6 +123,7 @@ deduplicates deduplication deepcopy deferrable +DEP deprecations deserialization deserialize