1
0
mirror of https://github.com/django/django.git synced 2025-06-14 16:09:12 +00:00

Updated guidance to propose new feature ideas in contributing docs.

These changes include:
* Clarification of the new feature proposal and evaluation process.
* Reodering "points to consider" into reporting bugs section, since
  these are mostly trac-specific.
* Narrowing the guide on user interface bugs and features to just bugs.
* Updating documentation for Someday/Maybe triage stage.

Co-authored-by: Tim Schilling <schilling711@gmail.com>
Co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com>
Co-authored-by: Natalia <124304+nessita@users.noreply.github.com>
This commit is contained in:
Lily Foote 2025-04-27 14:54:05 +01:00 committed by nessita
parent 96c79be4e4
commit 188799e67c
5 changed files with 97 additions and 78 deletions

View File

@ -10,11 +10,16 @@ Reporting bugs and requesting features
not public. For further details, please see :doc:`our security not public. For further details, please see :doc:`our security
policies </internals/security>`. policies </internals/security>`.
Otherwise, before reporting a bug or requesting a new feature on the .. _reporting-bugs:
`ticket tracker <https://code.djangoproject.com/>`_, consider these points:
* Check that someone hasn't already filed the bug or feature request by Reporting bugs
`searching`_ or running `custom queries`_ in the ticket tracker. ==============
Before reporting a bug on the `ticket tracker
<https://code.djangoproject.com/>`_ consider these points:
* Check that someone hasn't already filed the bug report by `searching`_ or
running `custom queries`_ in the ticket tracker.
* Don't use the ticket system to ask support questions. Use the `Django Forum`_ * Don't use the ticket system to ask support questions. Use the `Django Forum`_
or the `Django Discord server`_ for that. or the `Django Discord server`_ for that.
@ -26,11 +31,6 @@ Otherwise, before reporting a bug or requesting a new feature on the
likely to get lost. If a particular ticket is controversial, please move the likely to get lost. If a particular ticket is controversial, please move the
discussion to the `Django Forum`_. discussion to the `Django Forum`_.
.. _reporting-bugs:
Reporting bugs
==============
Well-written bug reports are *incredibly* helpful. However, there's a certain Well-written bug reports are *incredibly* helpful. However, there's a certain
amount of overhead involved in working with any bug tracking system so your amount of overhead involved in working with any bug tracking system so your
help in keeping our ticket tracker as useful as possible is appreciated. In help in keeping our ticket tracker as useful as possible is appreciated. In
@ -57,11 +57,11 @@ particular:
To understand the lifecycle of your ticket once you have created it, refer to To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`. :doc:`triaging-tickets`.
Reporting user interface bugs and features Reporting user interface bugs
========================================== ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your bug or feature request touches on anything visual in nature, there If your bug impacts anything visual in nature, there are a few additional
are a few additional guidelines to follow: guidelines to follow:
* Include screenshots in your ticket which are the visual equivalent of a * Include screenshots in your ticket which are the visual equivalent of a
minimal test case. Show off the issue, not the crazy customizations minimal test case. Show off the issue, not the crazy customizations
@ -82,22 +82,28 @@ are a few additional guidelines to follow:
* Make sure to set the UI/UX flag on the ticket so interested parties can * Make sure to set the UI/UX flag on the ticket so interested parties can
find your ticket. find your ticket.
.. _requesting-features:
Requesting features Requesting features
=================== ===================
We're always trying to make Django better, and your feature requests are a key We're always trying to make Django better, and your feature requests are a key
part of that. Here are some tips on how to make a request most effectively: part of that. Here are some tips on how to make a request most effectively:
* Make sure the feature actually requires changes in Django's core. If your * Evaluate whether the feature idea requires changes in Django's core. If your
idea can be developed as an independent application or module — for idea can be developed as an independent application or module — for
instance, you want to support another database engine — we'll probably instance, you want to support another database engine — we'll probably
suggest that you develop it independently. Then, if your project gathers suggest that you develop it independently. Then, if your project gathers
sufficient community support, we may consider it for inclusion in Django. sufficient community support, we may consider it for inclusion in Django.
* First request the feature on the `Django Forum`_, not in the ticket tracker. * Propose the feature in the `new feature ideas`_ GitHub project (not in the
It'll get read more closely and reach a larger audience. This is even more ticket tracker) by creating a new item in the **Idea** column. This is where
important for large-scale feature requests. We like to discuss any big the community and the :ref:`Steering Council <steering-council>` evaluate new
changes to Django's core before actually working on them. ideas for the Django ecosystem. This step is especially important for large
or complex proposals. We prefer to discuss any significant changes to
Django's core before any development begins. In some cases, a feature may be
better suited as a third-party package, where it can evolve independently of
Django's release cycle.
* Describe clearly and concisely what the missing feature is and how you'd * Describe clearly and concisely what the missing feature is and how you'd
like to see it implemented. Include example code (non-functional is OK) like to see it implemented. Include example code (non-functional is OK)
@ -107,9 +113,6 @@ part of that. Here are some tips on how to make a request most effectively:
others understand where it fits in, and if there are already other ways of others understand where it fits in, and if there are already other ways of
achieving the same thing. achieving the same thing.
If there's a consensus agreement on the feature, then it's appropriate to
create a ticket. Include a link to the discussion in the ticket description.
See also: :ref:`documenting-new-features`. See also: :ref:`documenting-new-features`.
Requesting performance optimizations Requesting performance optimizations
@ -126,8 +129,28 @@ benchmarks.
How we make decisions How we make decisions
===================== =====================
Whenever possible, we strive for a rough consensus. To that end, we'll often Whenever possible, we aim for rough consensus. Emoji reactions are used on
have informal votes on the Django Forum about a feature. In these votes we issues within the `new feature ideas`_ GitHub project to track community
feedback. The following meanings are assigned to each reaction:
* 👍: I support this feature and would use it
* 👎: I oppose this feature or believe it would cause issues for me or Django
* 😕: I have no strong opinion on this feature
* 🎉: This feature seems like a straightforward and beneficial addition
The :ref:`Steering Council <steering-council>` will regularly review the ideas
in the project, moving those with community support through the following
stages:
* Idea
* Approved - Idea refinement - Team creation
* In progress
* Working solution - Review - Feedback
* Needs maintainer (Django only)
* Done
Occasionally, discussions on feature ideas or the direction of Django may take
place on the Django Forum. These discussions may include informal votes, which
follow the voting style invented by Apache and used on Python itself, where follow the voting style invented by Apache and used on Python itself, where
votes are given as +1, +0, -0, or -1. votes are given as +1, +0, -0, or -1.
Roughly translated, these votes mean: Roughly translated, these votes mean:
@ -144,27 +167,8 @@ Roughly translated, these votes mean:
Although these votes are informal, they'll be taken very seriously. After a Although these votes are informal, they'll be taken very seriously. After a
suitable voting period, if an obvious consensus arises we'll follow the votes. suitable voting period, if an obvious consensus arises we'll follow the votes.
However, consensus is not always possible. If consensus cannot be reached, or
if the discussion toward a consensus fizzles out without a concrete decision,
the decision may be deferred to the :ref:`steering council <steering-council>`.
Internally, the steering council will use the same voting mechanism. A
proposition will be considered carried if:
* There are at least three "+1" votes from members of the steering council.
* There is no "-1" vote from any member of the steering council.
Votes should be submitted within a week.
Since this process allows any steering council member to veto a proposal, a
"-1" vote should be accompanied by an explanation of what it would take to
convert that "-1" into at least a "+0".
Votes on technical matters should be announced and held in public on the
`Django Forum`_.
.. _searching: https://code.djangoproject.com/search .. _searching: https://code.djangoproject.com/search
.. _custom queries: https://code.djangoproject.com/query .. _custom queries: https://code.djangoproject.com/query
.. _Django Forum: https://forum.djangoproject.com/ .. _Django Forum: https://forum.djangoproject.com/
.. _Django Discord server: https://chat.djangoproject.com .. _Django Discord server: https://chat.djangoproject.com
.. _new feature ideas: https://github.com/orgs/django/projects/24/

View File

@ -107,8 +107,13 @@ Explore additional avenues of contributing to Django beyond coding. Django's
`ticket tracker`_ is the central hub for managing issues, improvements, and `ticket tracker`_ is the central hub for managing issues, improvements, and
contributions to Django. It's a valuable resource where you can report bugs you contributions to Django. It's a valuable resource where you can report bugs you
encounter or assist in triaging existing tickets to ensure a smooth development encounter or assist in triaging existing tickets to ensure a smooth development
workflow. Explore the ways you can make a difference below, and join us in workflow.
making Django better for everyone.
Django also has a :ref:`process for suggesting ideas <requesting-features>`
where you can join the community in discussing ideas for new features.
Explore the ways you can make a difference below, and join us in making Django
better for everyone.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

View File

@ -3,11 +3,10 @@ Triaging tickets
================ ================
Django uses Trac_ for managing the work on the code base. Trac is a Django uses Trac_ for managing the work on the code base. Trac is a
community-tended garden of the bugs people have found and the features people community-tended garden of the bugs people have found and the features Django
would like to see added. As in any garden, sometimes there are weeds to be has decided to add. As in any garden, sometimes there are weeds to be pulled
pulled and sometimes there are flowers and vegetables that need picking. We need and sometimes there are flowers and vegetables that need picking. We need your
your help to sort out one from the other, and in the end, we all benefit help to sort out one from the other, and in the end, we all benefit together.
together.
Like all gardens, we can aspire to perfection, but in reality there's no such Like all gardens, we can aspire to perfection, but in reality there's no such
thing. Even in the most pristine garden there are still snails and insects. thing. Even in the most pristine garden there are still snails and insects.
@ -33,10 +32,10 @@ without **you**!
Triage workflow Triage workflow
=============== ===============
Unfortunately, not all bug reports and feature requests in the ticket tracker Unfortunately, not all reports in the ticket tracker provide all the
provide all the :doc:`required details<bugs-and-features>`. A number of :doc:`required details<bugs-and-features>`. A number of tickets have proposed
tickets have proposed solutions, but those don't necessarily meet all the solutions, but those don't necessarily meet all the requirements :ref:`adhering
requirements :ref:`adhering to the guidelines for contributing <patch-style>`. to the guidelines for contributing <patch-style>`.
One way to help out is to *triage* tickets that have been created by other One way to help out is to *triage* tickets that have been created by other
users. users.
@ -102,8 +101,8 @@ Unreviewed
---------- ----------
The ticket has not been reviewed by anyone who felt qualified to make a The ticket has not been reviewed by anyone who felt qualified to make a
judgment about whether the ticket contained a valid issue, a viable feature, judgment about whether the ticket contained a valid issue or ought to be closed
or ought to be closed for any of the various reasons. for any of the various reasons.
Accepted Accepted
-------- --------
@ -118,11 +117,12 @@ Beyond that there are several considerations:
means you could safely start writing a fix for it. This is generally more means you could safely start writing a fix for it. This is generally more
true for the case of accepted bugs than accepted features. A ticket for a bug true for the case of accepted bugs than accepted features. A ticket for a bug
that has been accepted means that the issue has been verified by at least one that has been accepted means that the issue has been verified by at least one
triager as a legitimate bug - and should probably be fixed if possible. An triager as a legitimate bug - and should probably be fixed if possible.
accepted new feature may only mean that one triager thought the feature would
be good to have, but this alone does not represent a consensus view or imply For new features, accepted tickets should only exist after the idea has gone
with any certainty that a patch will be accepted for that feature. Seek more through the appropriate :ref:`process for suggesting new features
feedback before writing an extensive contribution if you are in doubt. <requesting-features>` and received community and :ref:`Steering Council
<steering-council>` approval, or been accepted in a DEP.
* **Accepted + Has Patch** * **Accepted + Has Patch**
@ -154,12 +154,10 @@ Someday/Maybe
------------- -------------
This stage isn't shown on the diagram. It's used sparingly to keep track of This stage isn't shown on the diagram. It's used sparingly to keep track of
high-level ideas or long-term feature requests. long-term changes.
These tickets are uncommon and overall less useful since they don't describe These tickets are uncommon and overall less useful since they don't describe
concrete actionable issues. They are enhancement requests that we might concrete actionable issues.
consider adding someday to the framework if an excellent patch is submitted.
They are not a high priority.
Other triage attributes Other triage attributes
======================= =======================

View File

@ -36,7 +36,8 @@ and time availability), claim it by following these steps:
reset it using the `password reset page`_. reset it using the `password reset page`_.
* If a ticket for this issue doesn't exist yet, create one in our * If a ticket for this issue doesn't exist yet, create one in our
`ticket tracker`_. `ticket tracker`_. Remember that proposals for new features should follow
the :ref:`process for suggesting new features <requesting-features>`.
* If a ticket for this issue already exists, make sure nobody else has * If a ticket for this issue already exists, make sure nobody else has
claimed it. To do this, look at the "Owned by" section of the ticket. claimed it. To do this, look at the "Owned by" section of the ticket.
@ -154,11 +155,20 @@ or introduces breaking changes.
The following are different approaches for gaining feedback from the community. The following are different approaches for gaining feedback from the community.
The new feature ideas tracker
-----------------------------
If you have an idea for a new feature, please create a new proposal (or join an
existing discussion) following the :ref:`process for suggesting new features
<requesting-features>`. You should explain the need for the change, go into
details of the approach and discuss alternatives.
The Django Forum The Django Forum
---------------- ----------------
You can propose a change on the `Django Forum`_. You should explain the need You can propose a change (that is not a new feature idea) on the
for the change, go into details of the approach and discuss alternatives. `Django Forum`_. 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. Please include a link to such discussions in your contributions.
@ -174,8 +184,8 @@ third-party package first. You can iterate on the public API much faster, while
also validating the need for the feature. also validating the need for the feature.
Once this package becomes stable and there are clear benefits of incorporating Once this package becomes stable and there are clear benefits of incorporating
aspects into Django core, starting a discussion on the `Django Forum`_ would be aspects into Django core, the next step is to propose its inclusion by
the next step. following the :ref:`process for suggesting new features <requesting-features>`.
Django Enhancement Proposal (DEP) Django Enhancement Proposal (DEP)
--------------------------------- ---------------------------------
@ -187,9 +197,10 @@ specifications of features, along with rationales. DEPs are also the primary
mechanism for proposing and collecting community input on major new features. mechanism for proposing and collecting community input on major new features.
Before considering writing a DEP, it is recommended to first open a discussion Before considering writing a DEP, it is recommended to first open a discussion
on the `Django Forum`_. This allows the community to provide feedback and helps following the :ref:`process for suggesting new features <requesting-features>`.
refine the proposal. Once the DEP is ready the :ref:`Steering Council This allows the community to provide feedback and helps refine the proposal.
<steering-council>` votes on whether to accept it. 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: Some examples of DEPs that have been approved and fully implemented:

View File

@ -7,7 +7,8 @@ Introduction
Interested in giving back to the community a little? Maybe you've found a bug Interested in giving back to the community a little? Maybe you've found a bug
in Django that you'd like to see fixed, or maybe there's a small feature you in Django that you'd like to see fixed, or maybe there's a small feature you
want added. want added (but remember that proposals for new features should follow the
:ref:`process for suggesting new features <requesting-features>`).
Contributing back to Django itself is the best way to see your own concerns Contributing back to Django itself is the best way to see your own concerns
addressed. This may seem daunting at first, but it's a well-traveled path with addressed. This may seem daunting at first, but it's a well-traveled path with
@ -264,11 +265,11 @@ __ https://djangoci.com
<running-unit-tests-settings>`. When making UI changes, you will need to <running-unit-tests-settings>`. When making UI changes, you will need to
:ref:`run the Selenium tests <running-selenium-tests>`. :ref:`run the Selenium tests <running-selenium-tests>`.
Working on a feature Working on an approved new feature
==================== ==================================
For this tutorial, we'll work on a "fake ticket" as a case study. Here are the For this tutorial, we'll work on a "fake accepted ticket" as a case study. Here
imaginary details: are the imaginary details:
.. admonition:: Ticket #99999 -- Allow making toast .. admonition:: Ticket #99999 -- Allow making toast