Debian Codegraph @

docs/internals/contributing/bugs-and-features.txt

raw
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/