mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-06-02 18:19:11 +00:00
Code Issues 32 Releases Wiki Activity

Updated guidance to propose new feature ideas in contributing docs.

Browse Source 
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/internals/contributing/bugs-and-features.txt
View File

@ -10,11 +10,16 @@ Reporting bugs and requesting features
not public. For further details, please see :doc:`our security
policies </internals/security>`.
Otherwise, before reporting a bug or requesting a new feature on the
`ticket tracker <https://code.djangoproject.com/>`_, consider these points:
.. _reporting-bugs:
* Check that someone hasn't already filed the bug or feature request by
`searching`_ or running `custom queries`_ in the ticket tracker.
Reporting bugs
==============
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`_
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
discussion to the `Django Forum`_.
.. _reporting-bugs:
Reporting bugs
==============
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
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
: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
are a few additional guidelines to follow:
If your bug impacts anything visual in nature, there are a few additional
guidelines to follow:
* Include screenshots in your ticket which are the visual equivalent of a
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
find your ticket.
.. _requesting-features:
Requesting features
===================
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:
* 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
instance, you want to support another database engine — we'll probably
suggest that you develop it independently. Then, if your project gathers
sufficient community support, we may consider it for inclusion in Django.
* First request the feature on the `Django Forum`_, not in the ticket tracker.
It'll get read more closely and reach a larger audience. This is even more
important for large-scale feature requests. We like to discuss any big
changes to Django's core before actually working on them.
* Propose the feature in the `new feature ideas`_ GitHub project (not in the
ticket tracker) by creating a new item in the **Idea** column. This is where
the community and the :ref:`Steering Council <steering-council>` evaluate new
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
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
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`.
Requesting performance optimizations
@ -126,8 +129,28 @@ benchmarks.
How we make decisions
=====================
Whenever possible, we strive for a rough consensus. To that end, we'll often
have informal votes on the Django Forum about a feature. In these votes we
Whenever possible, we aim for rough consensus. Emoji reactions are used on
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
votes are given as +1, +0, -0, or -1.
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
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
.. _custom queries: https://code.djangoproject.com/query
.. _Django Forum: https://forum.djangoproject.com/
.. _Django Discord server: https://chat.djangoproject.com
.. _new feature ideas: https://github.com/orgs/django/projects/24/

9
docs/internals/contributing/index.txt
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
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
workflow. Explore the ways you can make a difference below, and join us in
making Django better for everyone.
workflow.
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::
:maxdepth: 2

38
docs/internals/contributing/triaging-tickets.txt
View File

@ -3,11 +3,10 @@ Triaging tickets
================
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
would like to see added. As in any garden, sometimes there are weeds to be
pulled and sometimes there are flowers and vegetables that need picking. We need
your help to sort out one from the other, and in the end, we all benefit
together.
community-tended garden of the bugs people have found and the features Django
has decided to add. As in any garden, sometimes there are weeds to be pulled
and sometimes there are flowers and vegetables that need picking. We need your
help to sort out one from the other, and in the end, we all benefit together.
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.
@ -33,10 +32,10 @@ without **you**!
Triage workflow
===============
Unfortunately, not all bug reports and feature requests in the ticket tracker
provide all the :doc:`required details<bugs-and-features>`. A number of
tickets have proposed solutions, but those don't necessarily meet all the
requirements :ref:`adhering to the guidelines for contributing <patch-style>`.
Unfortunately, not all reports in the ticket tracker provide all the
:doc:`required details<bugs-and-features>`. A number of tickets have proposed
solutions, but those don't necessarily meet all the requirements :ref:`adhering
to the guidelines for contributing <patch-style>`.
One way to help out is to *triage* tickets that have been created by other
users.
@ -102,8 +101,8 @@ Unreviewed
----------
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,
or ought to be closed for any of the various reasons.
judgment about whether the ticket contained a valid issue or ought to be closed
for any of the various reasons.
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
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
triager as a legitimate bug - and should probably be fixed if possible. An
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
with any certainty that a patch will be accepted for that feature. Seek more
feedback before writing an extensive contribution if you are in doubt.
triager as a legitimate bug - and should probably be fixed if possible.
For new features, accepted tickets should only exist after the idea has gone
through the appropriate :ref:`process for suggesting new features
<requesting-features>` and received community and :ref:`Steering Council
<steering-council>` approval, or been accepted in a DEP.
* **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
high-level ideas or long-term feature requests.
long-term changes.
These tickets are uncommon and overall less useful since they don't describe
concrete actionable issues. They are enhancement requests that we might
consider adding someday to the framework if an excellent patch is submitted.
They are not a high priority.
concrete actionable issues.
Other triage attributes
=======================

27
docs/internals/contributing/writing-code/submitting-patches.txt
View File

@ -36,7 +36,8 @@ and time availability), claim it by following these steps:
reset it using the `password reset page`_.
* 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
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 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
----------------
You can propose a change on the `Django Forum`_. You should explain the need
for the change, go into details of the approach and discuss alternatives.
You can propose a change (that is not a new feature idea) on the
`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.
@ -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.
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
the next step.
aspects into Django core, the next step is to propose its inclusion by
following the :ref:`process for suggesting new features <requesting-features>`.
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.
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
refine the proposal. Once the DEP is ready the :ref:`Steering Council
<steering-council>` votes on whether to accept it.
following the :ref:`process for suggesting new features <requesting-features>`.
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:

11
docs/intro/contributing.txt
View File

@ -7,7 +7,8 @@ Introduction
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
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
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
: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
imaginary details:
For this tutorial, we'll work on a "fake accepted ticket" as a case study. Here
are the imaginary details:
.. admonition:: Ticket #99999 -- Allow making toast