diff options
Diffstat (limited to 'docs/internals/contributing/bugs-and-features.txt')
| -rw-r--r-- | docs/internals/contributing/bugs-and-features.txt | 150 |
1 files changed, 75 insertions, 75 deletions
diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 87c0f04aec..c3d5d762df 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -30,23 +30,23 @@ 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** read the :doc:`FAQ </faq/index>` to see if your issue might + be a well-known question. - * **Do** ask on `django-users`_ or `#django`_ *first* if you're not sure if - what you're seeing is a bug. +* **Do** ask on `django-users`_ or `#django`_ *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 an easy - way to confirm the bug quickly. +* **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 an easy + way to confirm the bug quickly. - * **Don't** post to `django-developers`_ just 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. +* **Don't** post to `django-developers`_ just 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`. @@ -67,27 +67,27 @@ Reporting security issues In the event of a confirmed vulnerability in Django itself, we will take the following actions: - * Acknowledge to the reporter that we've received the report and that a - fix is forthcoming. We'll give a rough timeline and ask the reporter - to keep the issue confidential until we announce it. +* Acknowledge to the reporter that we've received the report and that a + fix is forthcoming. We'll give a rough timeline and ask the reporter + to keep the issue confidential until we announce it. - * Focus on developing a fix as quickly as possible and produce patches - against the current and two previous releases. +* Focus on developing a fix as quickly as possible and produce patches + against the current and two previous releases. - * Determine a go-public date for announcing the vulnerability and the fix. - To try to mitigate a possible "arms race" between those applying the - patch and those trying to exploit the hole, we will not announce - security problems immediately. +* Determine a go-public date for announcing the vulnerability and the fix. + To try to mitigate a possible "arms race" between those applying the + patch and those trying to exploit the hole, we will not announce + security problems immediately. - * Pre-notify third-party distributors of Django ("vendors"). We will send - these vendor notifications through private email which will include - documentation of the vulnerability, links to the relevant patch(es), and - a request to keep the vulnerability confidential until the official - go-public date. +* Pre-notify third-party distributors of Django ("vendors"). We will send + these vendor notifications through private email which will include + documentation of the vulnerability, links to the relevant patch(es), and + a request to keep the vulnerability confidential until the official + go-public date. - * Publicly announce the vulnerability and the fix on the pre-determined - go-public date. This will probably mean a new release of Django, but - in some cases it may simply be patches against current releases. +* Publicly announce the vulnerability and the fix on the pre-determined + go-public date. This will probably mean a new release of Django, but + in some cases it may simply be patches against current releases. Reporting user interface bugs and features ------------------------------------------ @@ -95,25 +95,25 @@ 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 testcase. 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 which changes the look or behavior of Django's - UI, you **must** attach before *and* after screenshots/screencasts. - Tickets lacking these are difficult for triagers and core developers to - assess quickly. +* Include screenshots in your ticket which are the visual equivalent of a + minimal testcase. Show off the issue, not the crazy customizations + you've made to your browser. - * 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. +* 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. - * Make sure to set the UI/UX flag on the ticket so interested parties can - find your ticket. +* If you're offering a patch which changes the look or behavior of Django's + UI, you **must** attach before *and* after screenshots/screencasts. + Tickets lacking these are difficult for triagers and core developers 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 ------------------- @@ -121,27 +121,27 @@ 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 to develop it independently. Then, if your project - gathers sufficient community support, we may consider it for inclusion in - Django. +* 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 to 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-developers`_ list, not in the - ticket tracker. It'll get read more closely if it's on the mailing list. - This is even more important for large-scale feature requests. We like to - discuss any big changes to Django's core on the mailing list before - actually working on them. +* First request the feature on the `django-developers`_ list, not in the + ticket tracker. It'll get read more closely if it's on the mailing list. + This is even more important for large-scale feature requests. We like to + discuss any big changes to Django's core on the mailing list 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. +* 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. In some cases this is obvious, but - since Django is designed to help real developers get real work done, - you'll need to explain it, if it isn't obvious why the feature would be - useful. +* Explain *why* you'd like the feature. In some cases this is obvious, but + since Django is designed to help real developers get real work done, + you'll need to explain it, if it isn't obvious why the feature would be + useful. If core developers agree on the feature, then it's appropriate to create a ticket. Include a link the discussion on `django-developers`_ in the ticket @@ -165,14 +165,14 @@ have informal votes on `django-developers`_ 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." +* +1: "I love the idea and I'm strongly committed to it." - * +0: "Sounds OK to me." +* +0: "Sounds OK to me." - * -0: "I'm not thrilled, but I won't stand in the way." +* -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." +* -1: "I strongly disagree and would be very unhappy to see the idea turn + into reality." Although these votes on `django-developers`_ are informal, they'll be taken very seriously. After a suitable voting period, if an obvious consensus arises we'll @@ -186,12 +186,12 @@ Any :doc:`core committer</internals/committers>` may call for a formal vote using the same voting mechanism above. A proposition will be considered carried by the core team if: - * There are three "+1" votes from members of the core team. +* There are three "+1" votes from members of the core team. - * There is no "-1" vote from any member of the core team. +* There is no "-1" vote from any member of the core team. - * The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their - positive or negative veto. +* The :ref:`BDFLs<django-bdfls>` haven't stepped in and executed their + positive or negative veto. When calling for a vote, the caller should specify a deadline by which votes must be received. One week is generally suggested as the minimum |