From 817ed81aea4255b0228d551ef035b904cb2a293a Mon Sep 17 00:00:00 2001 From: Lily Foote Date: Sun, 27 Apr 2025 14:54:05 +0100 Subject: [PATCH] [5.2.x] 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 Co-authored-by: Sarah Boyce <42296566+sarahboyce@users.noreply.github.com> Co-authored-by: Natalia <124304+nessita@users.noreply.github.com> Backport of 188799e67c2c497419f448359775930c866fe28d from main. --- .../contributing/bugs-and-features.txt | 90 ++++++++++--------- docs/internals/contributing/index.txt | 9 +- .../contributing/triaging-tickets.txt | 38 ++++---- .../writing-code/submitting-patches.txt | 27 ++++-- docs/intro/contributing.txt | 11 +-- 5 files changed, 97 insertions(+), 78 deletions(-) diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index ad667e3c58..53ff3596cc 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -10,11 +10,16 @@ Reporting bugs and requesting features not public. For further details, please see :doc:`our security policies `. -Otherwise, before reporting a bug or requesting a new feature on the -`ticket tracker `_, consider these points: +.. _reporting-bugs: -* Check that someone hasn't already filed the bug or feature request by - `searching`_ or running `custom queries`_ in the ticket tracker. +Reporting bugs +============== + +Before reporting a bug on the `ticket tracker +`_ 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`_ 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 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 @@ -57,11 +57,11 @@ particular: To understand the lifecycle of your ticket once you have created it, refer to :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 -are a few additional guidelines to follow: +If your bug impacts 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 @@ -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 find your ticket. +.. _requesting-features: + 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 +* Evaluate whether the feature idea 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. +* Propose the feature in the `new feature ideas`_ GitHub project (not in the + ticket tracker) by creating a new item in the **Idea** column. This is where + the community and the :ref:`Steering Council ` evaluate new + 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 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 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 @@ -126,8 +129,28 @@ benchmarks. 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 +Whenever possible, we aim for rough consensus. Emoji reactions are used on +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 ` 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 votes are given as +1, +0, -0, or -1. 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 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 `. - -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 +.. _new feature ideas: https://github.com/orgs/django/projects/24/ diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt index de53ece43e..0749bc9a6e 100644 --- a/docs/internals/contributing/index.txt +++ b/docs/internals/contributing/index.txt @@ -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 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 -workflow. Explore the ways you can make a difference below, and join us in -making Django better for everyone. +workflow. + +Django also has a :ref:`process for suggesting ideas ` +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:: :maxdepth: 2 diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index ba5ab690c0..c0d87dcb7c 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -3,11 +3,10 @@ Triaging tickets ================ 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 -would like to see added. As in any garden, sometimes there are weeds to be -pulled and sometimes there are flowers and vegetables that need picking. We need -your help to sort out one from the other, and in the end, we all benefit -together. +community-tended garden of the bugs people have found and the features Django +has decided to add. As in any garden, sometimes there are weeds to be pulled +and sometimes there are flowers and vegetables that need picking. We need your +help to sort out one from the other, and in the end, we all benefit together. 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. @@ -33,10 +32,10 @@ without **you**! Triage workflow =============== -Unfortunately, not all bug reports and feature requests in the ticket tracker -provide all the :doc:`required details`. A number of -tickets have proposed solutions, but those don't necessarily meet all the -requirements :ref:`adhering to the guidelines for contributing `. +Unfortunately, not all reports in the ticket tracker provide all the +:doc:`required details`. A number of tickets have proposed +solutions, but those don't necessarily meet all the requirements :ref:`adhering +to the guidelines for contributing `. One way to help out is to *triage* tickets that have been created by other users. @@ -102,8 +101,8 @@ Unreviewed ---------- 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, -or ought to be closed for any of the various reasons. +judgment about whether the ticket contained a valid issue or ought to be closed +for any of the various reasons. 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 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 - triager as a legitimate bug - and should probably be fixed if possible. An - 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 - with any certainty that a patch will be accepted for that feature. Seek more - feedback before writing an extensive contribution if you are in doubt. + triager as a legitimate bug - and should probably be fixed if possible. + + For new features, accepted tickets should only exist after the idea has gone + through the appropriate :ref:`process for suggesting new features + ` and received community and :ref:`Steering Council + ` approval, or been accepted in a DEP. * **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 -high-level ideas or long-term feature requests. +long-term changes. These tickets are uncommon and overall less useful since they don't describe -concrete actionable issues. They are enhancement requests that we might -consider adding someday to the framework if an excellent patch is submitted. -They are not a high priority. +concrete actionable issues. Other triage attributes ======================= diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 424cc8b944..fe354a0ba1 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -36,7 +36,8 @@ and time availability), claim it by following these steps: reset it using the `password reset page`_. * 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 `. * 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. @@ -154,11 +155,20 @@ or introduces breaking changes. 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 +`. You should explain the need for the change, go into +details of the approach and discuss alternatives. + The Django Forum ---------------- -You can propose a change on the `Django Forum`_. You should explain the need -for the change, go into details of the approach and discuss alternatives. +You can propose a change (that is not a new feature idea) on the +`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. @@ -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. 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 -the next step. +aspects into Django core, the next step is to propose its inclusion by +following the :ref:`process for suggesting new features `. 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. 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 -refine the proposal. Once the DEP is ready the :ref:`Steering Council -` votes on whether to accept it. +following the :ref:`process for suggesting new features `. +This allows the community to provide feedback and helps refine the proposal. +Once the DEP is ready the :ref:`Steering Council ` votes on +whether to accept it. Some examples of DEPs that have been approved and fully implemented: diff --git a/docs/intro/contributing.txt b/docs/intro/contributing.txt index 6b3249b823..65789bdc78 100644 --- a/docs/intro/contributing.txt +++ b/docs/intro/contributing.txt @@ -7,7 +7,8 @@ Introduction 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 -want added. +want added (but remember that proposals for new features should follow the +:ref:`process for suggesting new features `). 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 @@ -264,11 +265,11 @@ __ https://djangoci.com `. When making UI changes, you will need to :ref:`run the 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 -imaginary details: +For this tutorial, we'll work on a "fake accepted ticket" as a case study. Here +are the imaginary details: .. admonition:: Ticket #99999 -- Allow making toast