======================================
Reporting bugs and requesting features
======================================

.. Important::

    Please report security issues **only** to
    security@djangoproject.com.  This is a private list only open to
    long-time, highly trusted Django developers, and its archives are
    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:

* Check that someone hasn't already filed the bug or feature request 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.

* Don't reopen issues that have been marked "wontfix" without finding consensus
  to do so on the `Django Forum`_.

* Don't use the ticket tracker for lengthy discussions, because they're
  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
particular:

* **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
  be a well-known question.

* **Do** ask on `Django Forum`_ or the `Django Discord server`_ *first* if
  you're not sure if what you're seeing is a bug.

* **Do** write complete, reproducible, specific bug reports. You must
  include a clear, concise description of the problem, and a set of
  instructions for replicating it. Add as much debug information as you can:
  code snippets, test cases, exception backtraces, screenshots, etc. A nice
  small test case is the best way to report a bug, as it gives us a
  helpful way to confirm the bug quickly.

* **Don't** post to `Django Forum`_ only to announce that you have filed a
  bug report. All the tickets are mailed to another list, |django-updates|,
  which is tracked by developers and interested community members; we see them
  as they are filed.

To understand the lifecycle of your ticket once you have created it, refer to
:doc:`triaging-tickets`.

Reporting user interface bugs and features
==========================================

If your bug or feature request touches on 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
  you've made to your browser.

* If the issue is difficult to show off using a still image, consider
  capturing a *brief* screencast. If your software permits it, capture only
  the relevant area of the screen.

* If you're offering a patch that changes the look or behavior of Django's
  UI, you **must** attach before *and* after screenshots/screencasts.
  Tickets lacking these are difficult for triagers to assess quickly.

* Screenshots don't absolve you of other good reporting practices. Make sure
  to include URLs, code snippets, and step-by-step instructions on how to
  reproduce the behavior visible in the screenshots.

* Make sure to set the UI/UX flag on the ticket so interested parties can
  find your ticket.

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
  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.

* 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)
  if possible.

* Explain *why* you'd like the feature. Explaining a minimal use case will help
  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
====================================

Reports of a performance regression, or suggested performance optimizations,
should provide benchmarks and commands for the ticket triager to reproduce.

See the :ref:`django-asv-benchmarks` for more details of Django's existing
benchmarks.

.. _how-we-make-decisions:

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
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:

* +1: "I love the idea and I'm strongly committed to it."

* +0: "Sounds OK to me."

* -0: "I'm not thrilled, but I won't stand in the way."

* -1: "I strongly disagree and would be very unhappy to see the idea turn
  into reality."

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
