| 1 |
====================================== |
| 2 |
Reporting bugs and requesting features |
| 3 |
====================================== |
| 4 |
|
| 5 |
.. Important:: |
| 6 |
|
| 7 |
Please report security issues **only** to |
| 8 |
[email protected]. This is a private list only open to |
| 9 |
long-time, highly trusted Django developers, and its archives are |
| 10 |
not public. For further details, please see :doc:`our security |
| 11 |
policies </internals/security>`. |
| 12 |
|
| 13 |
.. _reporting-bugs: |
| 14 |
|
| 15 |
Reporting bugs |
| 16 |
============== |
| 17 |
|
| 18 |
Before reporting a bug on the `ticket tracker |
| 19 |
<https://code.djangoproject.com/>`_ consider these points: |
| 20 |
|
| 21 |
* Check that someone hasn't already filed the bug report by `searching`_ or |
| 22 |
running `custom queries`_ in the ticket tracker. |
| 23 |
|
| 24 |
* Don't use the ticket system to ask support questions. Use the `Django Forum`_ |
| 25 |
or the `Django Discord server`_ for that. |
| 26 |
|
| 27 |
* Don't reopen issues that have been marked "wontfix" without finding consensus |
| 28 |
to do so on the `Django Forum`_. |
| 29 |
|
| 30 |
* Don't use the ticket tracker for lengthy discussions, because they're |
| 31 |
likely to get lost. If a particular ticket is controversial, please move the |
| 32 |
discussion to the `Django Forum`_. |
| 33 |
|
| 34 |
Well-written bug reports are *incredibly* helpful. However, there's a certain |
| 35 |
amount of overhead involved in working with any bug tracking system so your |
| 36 |
help in keeping our ticket tracker as useful as possible is appreciated. In |
| 37 |
particular: |
| 38 |
|
| 39 |
* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might |
| 40 |
be a well-known question. |
| 41 |
|
| 42 |
* **Do** ask on `Django Forum`_ or the `Django Discord server`_ *first* if |
| 43 |
you're not sure if what you're seeing is a bug. |
| 44 |
|
| 45 |
* **Do** write complete, reproducible, specific bug reports. You must |
| 46 |
include a clear, concise description of the problem, and a set of |
| 47 |
instructions for replicating it. Add as much debug information as you can: |
| 48 |
code snippets, test cases, exception backtraces, screenshots, etc. A nice |
| 49 |
small test case is the best way to report a bug, as it gives us a |
| 50 |
helpful way to confirm the bug quickly. |
| 51 |
|
| 52 |
* **Don't** post to `Django Forum`_ only to announce that you have filed a |
| 53 |
bug report. All the tickets are mailed to another list, |django-updates|, |
| 54 |
which is tracked by developers and interested community members; we see them |
| 55 |
as they are filed. |
| 56 |
|
| 57 |
To understand the lifecycle of your ticket once you have created it, refer to |
| 58 |
:doc:`triaging-tickets`. |
| 59 |
|
| 60 |
Reporting user interface bugs |
| 61 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 62 |
|
| 63 |
If your bug impacts anything visual in nature, there are a few additional |
| 64 |
guidelines to follow: |
| 65 |
|
| 66 |
* Include screenshots in your ticket which are the visual equivalent of a |
| 67 |
minimal test case. Show off the issue, not the crazy customizations |
| 68 |
you've made to your browser. |
| 69 |
|
| 70 |
* If the issue is difficult to show off using a still image, consider |
| 71 |
capturing a *brief* screencast. If your software permits it, capture only |
| 72 |
the relevant area of the screen. |
| 73 |
|
| 74 |
* If you're offering a patch that changes the look or behavior of Django's |
| 75 |
UI, you **must** attach before *and* after screenshots/screencasts. |
| 76 |
Tickets lacking these are difficult for triagers to assess quickly. |
| 77 |
|
| 78 |
* Screenshots don't absolve you of other good reporting practices. Make sure |
| 79 |
to include URLs, code snippets, and step-by-step instructions on how to |
| 80 |
reproduce the behavior visible in the screenshots. |
| 81 |
|
| 82 |
* Make sure to set the UI/UX flag on the ticket so interested parties can |
| 83 |
find your ticket. |
| 84 |
|
| 85 |
* If the issue relates to accessibility, please link to the relevant |
| 86 |
:ref:`accessibility standard <accessibility-standards>` if applicable. |
| 87 |
|
| 88 |
.. _requesting-features: |
| 89 |
|
| 90 |
Requesting features |
| 91 |
=================== |
| 92 |
|
| 93 |
We're always trying to make Django better, and your feature requests are a key |
| 94 |
part of that. Here are some tips on how to make a request most effectively: |
| 95 |
|
| 96 |
* Evaluate whether the feature idea requires changes in Django's core. If your |
| 97 |
idea can be developed as an independent application or module — for |
| 98 |
instance, you want to support another database engine — we'll probably |
| 99 |
suggest that you develop it independently. Then, if your project gathers |
| 100 |
sufficient community support, we may consider it for inclusion in Django. |
| 101 |
|
| 102 |
* Propose the feature in the `new feature ideas`_ GitHub project (not in the |
| 103 |
ticket tracker) by creating a new item in the **Idea** column. This is where |
| 104 |
the community and the :ref:`Steering Council <steering-council>` evaluate new |
| 105 |
ideas for the Django ecosystem. This step is especially important for large |
| 106 |
or complex proposals. We prefer to discuss any significant changes to |
| 107 |
Django's core before any development begins. In some cases, a feature may be |
| 108 |
better suited as a third-party package, where it can evolve independently of |
| 109 |
Django's release cycle. |
| 110 |
|
| 111 |
* Describe clearly and concisely what the missing feature is and how you'd |
| 112 |
like to see it implemented. Include example code (non-functional is OK) |
| 113 |
if possible. |
| 114 |
|
| 115 |
* Explain *why* you'd like the feature. Explaining a minimal use case will help |
| 116 |
others understand where it fits in, and if there are already other ways of |
| 117 |
achieving the same thing. |
| 118 |
|
| 119 |
See also: :ref:`documenting-new-features`. |
| 120 |
|
| 121 |
Requesting performance optimizations |
| 122 |
==================================== |
| 123 |
|
| 124 |
Reports of a performance regression, or suggested performance optimizations, |
| 125 |
should provide benchmarks and commands for the ticket triager to reproduce. |
| 126 |
|
| 127 |
See the :ref:`django-asv-benchmarks` for more details of Django's existing |
| 128 |
benchmarks. |
| 129 |
|
| 130 |
.. _how-we-make-decisions: |
| 131 |
|
| 132 |
How we make decisions |
| 133 |
===================== |
| 134 |
|
| 135 |
Whenever possible, we aim for rough consensus. Emoji reactions are used on |
| 136 |
issues within the `new feature ideas`_ GitHub project to track community |
| 137 |
feedback. The following meanings are assigned to each reaction: |
| 138 |
|
| 139 |
* 👍: I support this feature and would use it |
| 140 |
* 👎: I oppose this feature or believe it would cause issues for me or Django |
| 141 |
* 😕: I have no strong opinion on this feature |
| 142 |
* 🎉: This feature seems like a straightforward and beneficial addition |
| 143 |
|
| 144 |
The :ref:`Steering Council <steering-council>` will regularly review the ideas |
| 145 |
in the project, moving those with community support through the following |
| 146 |
stages: |
| 147 |
|
| 148 |
* Idea |
| 149 |
* Approved - Idea refinement - Team creation |
| 150 |
* In progress |
| 151 |
* Working solution - Review - Feedback |
| 152 |
* Needs maintainer (Django only) |
| 153 |
* Done |
| 154 |
|
| 155 |
Occasionally, discussions on feature ideas or the direction of Django may take |
| 156 |
place on the Django Forum. These discussions may include informal votes, which |
| 157 |
follow the voting style invented by Apache and used on Python itself, where |
| 158 |
votes are given as +1, +0, -0, or -1. |
| 159 |
Roughly translated, these votes mean: |
| 160 |
|
| 161 |
* +1: "I love the idea and I'm strongly committed to it." |
| 162 |
|
| 163 |
* +0: "Sounds OK to me." |
| 164 |
|
| 165 |
* -0: "I'm not thrilled, but I won't stand in the way." |
| 166 |
|
| 167 |
* -1: "I strongly disagree and would be very unhappy to see the idea turn |
| 168 |
into reality." |
| 169 |
|
| 170 |
Although these votes are informal, they'll be taken very seriously. After a |
| 171 |
suitable voting period, if an obvious consensus arises we'll follow the votes. |
| 172 |
|
| 173 |
.. _searching: https://code.djangoproject.com/search |
| 174 |
.. _custom queries: https://code.djangoproject.com/query |
| 175 |
.. _Django Forum: https://forum.djangoproject.com/ |
| 176 |
.. _Django Discord server: https://chat.djangoproject.com |
| 177 |
.. _new feature ideas: https://github.com/orgs/django/projects/24/ |