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:
parent
96c79be4e4
commit
188799e67c
@ -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/
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
=======================
|
=======================
|
||||||
|
@ -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:
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user