diff --git a/docs/faq/contributing.txt b/docs/faq/contributing.txt index 079a789197..17e730d96f 100644 --- a/docs/faq/contributing.txt +++ b/docs/faq/contributing.txt @@ -43,32 +43,28 @@ If your patch stands no chance of inclusion in Django, we won't ignore it -- we'll just close the ticket. So if your ticket is still open, it doesn't mean we're ignoring you; it just means we haven't had time to look at it yet. -When and how might I remind the core team of a patch I care about? -================================================================== +When and how might I remind the team of a patch I care about? +============================================================= A polite, well-timed message to the mailing list is one way to get attention. To determine the right time, you need to keep an eye on the schedule. If you -post your message when the core developers are trying to hit a feature -deadline or manage a planning phase, you're not going to get the sort of -attention you require. However, if you draw attention to a ticket when the -core developers are paying particular attention to bugs -- just before a bug -fixing sprint, or in the lead up to a beta release for example -- you're much -more likely to get a productive response. +post your message right before a release deadline, you're not likely to get the +sort of attention you require. Gentle IRC reminders can also work -- again, strategically timed if possible. During a bug sprint would be a very good time, for example. Another way to get traction is to pull several related tickets together. When -the core developers sit down to fix a bug in an area they haven't touched for +the someone sits down to review a bug in an area they haven't touched for a while, it can take a few minutes to remember all the fine details of how that area of code works. If you collect several minor bug fixes together into a similarly themed group, you make an attractive target, as the cost of coming up to speed on an area of code can be spread over multiple tickets. -Please refrain from emailing core developers personally, or repeatedly raising -the same issue over and over. This sort of behavior will not gain you any -additional attention -- certainly not the attention that you need in order to -get your pet bug addressed. +Please refrain from emailing anyone personally or repeatedly raising the same +issue over and over. This sort of behavior will not gain you any additional +attention -- certainly not the attention that you need in order to get your +issue addressed. But I've reminded you several times and you keep ignoring my patch! =================================================================== diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index 3e1c4d2e1d..858de4ad08 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -19,10 +19,8 @@ Otherwise, before reporting a bug or requesting a new feature on the * Don't use the ticket system to ask support questions. Use the |django-users| list or the `#django`_ IRC channel for that. -* Don't reopen issues that have been marked "wontfix" by a core developer. - This mark means that the decision has been made that we can't or won't fix - this particular issue. If you're not sure why, please ask - on |django-developers|. +* Don't reopen issues that have been marked "wontfix" without finding consensus + to do so on |django-developers|. * 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 @@ -75,8 +73,7 @@ are a few additional guidelines to follow: * 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. + 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 @@ -113,9 +110,9 @@ part of that. Here are some tips on how to make a request most effectively: 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 -description. +If there's a consensus agreement on the feature, then it's appropriate to +create a ticket. Include a link the discussion on |django-developers| in the +ticket description. As with most open-source projects, code talks. If you are willing to write the code for the feature yourself or, even better, if you've already written it, @@ -149,8 +146,7 @@ follow the votes. However, consensus is not always possible. If consensus cannot be reached, or if the discussion towards a consensus fizzles out without a concrete decision, -any :ref:`core team member ` may defer the decision to the -:ref:`technical board `. +the decision may be deferred to the :ref:`technical board `. Internally, the technical board will use the same voting mechanism. A proposition will be considered carried if: diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index 445e341dda..d42fdb8940 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -119,10 +119,9 @@ Django's Git repository: If you bring something up on |django-developers| and nobody responds, please don't take that to mean your idea is great and should be - implemented immediately because nobody contested it. Django's core - developers don't have a lot of time to read mailing-list discussions - immediately, so you may have to wait a couple of days before getting a - response. + implemented immediately because nobody contested it. Everyone doesn't always + have a lot of time to read mailing list discussions immediately, so you may + have to wait a couple of days before getting a response. * Write detailed commit messages in the past tense, not present tense. @@ -151,9 +150,8 @@ Django's Git repository: * Limit commits to the most granular change that makes sense. This means, use frequent small commits rather than infrequent large commits. For example, if implementing feature X requires a small change to library Y, - first commit the change to library Y, then commit feature X in a - separate commit. This goes a *long way* in helping all Django core - developers follow your changes. + first commit the change to library Y, then commit feature X in a separate + commit. This goes a *long way* in helping everyone follow your changes. * Separate bug fixes from feature changes. Bugfixes may need to be backported to the stable branch, according to the :ref:`backwards-compatibility policy diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index 379b0f8971..90fa97cf28 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -86,9 +86,9 @@ some advice to make your work on Django more useful and rewarding. When reading Trac, you need to take into account who says things, and when they were said. Support for an idea two years ago doesn't necessarily mean that the idea will still have support. You also need to pay attention to who - *hasn't* spoken -- for example, if a core team member hasn't been recently - involved in a discussion, then a ticket may not have the support required to - get into trunk. + *hasn't* spoken -- for example, if an experienced contributor hasn't been + recently involved in a discussion, then a ticket may not have the support + required to get into Django. * **Start small** @@ -99,15 +99,15 @@ some advice to make your work on Django more useful and rewarding. support first** This means getting someone else to confirm that a bug is real before you fix - the issue, and ensuring that the core team supports a proposed feature - before you go implementing it. + the issue, and ensuring that there's consensus on a proposed feature before + you go implementing it. * **Be bold! Leave feedback!** Sometimes it can be scary to put your opinion out to the world and say "this ticket is correct" or "this patch needs work", but it's the only way the project moves forward. The contributions of the broad Django community - ultimately have a much greater impact than that of the core team. We can't + ultimately have a much greater impact than that of any one person. We can't do it without **you**! * **Err on the side of caution when marking things Ready For Check-in** @@ -143,9 +143,9 @@ FAQ I do to get it committed?** First off, it's not personal. Django is entirely developed by volunteers - (even the core team), and sometimes folks just don't have time. The best - thing to do is to send a gentle reminder to the |django-developers| mailing - list asking for review on the ticket, or to bring it up in the + (except the Django fellow), and sometimes folks just don't have time. The + best thing to do is to send a gentle reminder to the |django-developers| + mailing list asking for review on the ticket, or to bring it up in the `#django-dev` IRC channel. 2. **I'm sure my ticket is absolutely 100% perfect, can I mark it as RFC diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index bad14dd54c..3f1c7768fc 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -40,8 +40,7 @@ tickets have patches, but those patches don't meet all the requirements of a :ref:`good patch`. One way to help out is to *triage* tickets that have been created by other -users. The core team and several community members work on this regularly, but -more help is always appreciated. +users. Most of the workflow is based around the concept of a ticket's :ref:`triage stages `. Each stage describes where in its @@ -57,9 +56,8 @@ Since a picture is worth a thousand words, let's start there: We've got two roles in this diagram: -* Committers (also called core developers): people with commit access who are - responsible for making decisions and integrating the contributions of the - community. +* Committers: people with commit access who are responsible for making the + final decision to merge a patch. * Ticket triagers: anyone in the Django community who chooses to become involved in Django's development process. Our Trac installation @@ -69,26 +67,25 @@ We've got two roles in this diagram: By way of example, here we see the lifecycle of an average ticket: -* Alice creates a ticket, and uploads an incomplete patch (no tests, incorrect - implementation). +* Alice creates a ticket and sends an incomplete pull request (no tests, + incorrect implementation). -* Bob reviews the patch, marks it "Accepted", "needs tests", and "patch needs - improvement", and leaves a comment telling Alice how the patch could be - improved. +* Bob reviews the pull request, marks the ticket as "Accepted", "needs tests", + and "patch needs improvement", and leaves a comment telling Alice how the + patch could be improved. -* Alice updates the patch, adding tests (but not changing the +* Alice updates the pull request, adding tests (but not changing the implementation). She removes the two flags. -* Charlie reviews the patch and resets the "patch needs improvement" flag with - another comment about improving the implementation. +* Charlie reviews the pull request and resets the "patch needs improvement" + flag with another comment about improving the implementation. -* Alice updates the patch, fixing the implementation. She removes the "patch - needs improvement" flag. +* Alice updates the pull request, fixing the implementation. She removes the + "patch needs improvement" flag. -* Daisy reviews the patch, and marks it RFC. +* Daisy reviews the pull request and marks the ticket as "Ready for checkin". -* Jacob, a core developer, reviews the RFC patch, applies it to his checkout, - and commits it. +* Jacob, a committer, reviews the pull request and merges it. Some tickets require much less feedback than this, but then again some tickets require much much more. @@ -154,8 +151,8 @@ RFC forever! What should I do?" Someday/Maybe ------------- -This stage isn't shown on the diagram. It's only used by core developers to -keep track of high-level ideas or long term feature requests. +This stage isn't shown on the diagram. It's used sparingly to keep track of +high-level ideas or long term feature requests. These tickets are uncommon and overall less useful since they don't describe concrete actionable issues. They are enhancement requests that we might @@ -297,8 +294,7 @@ If you do close a ticket, you should always make sure of the following: A ticket can be resolved in a number of ways: * fixed - Used by the core developers once a patch has been rolled into - Django and the issue is fixed. + Used once a patch has been rolled into Django and the issue is fixed. * invalid Used if the ticket is found to be incorrect. This means that the @@ -308,12 +304,13 @@ A ticket can be resolved in a number of ways: submit support queries as tickets). * wontfix - Used when a core developer decides that this request is not - appropriate for consideration in Django. This is usually chosen after - discussion in the |django-developers| mailing list. Feel free to - start or join in discussions of "wontfix" tickets on the - |django-developers| mailing list, but please do not reopen tickets - closed as "wontfix" by a :doc:`core developer`. + Used when a someone decides that the request isn't appropriate for + consideration in Django. Sometimes a ticket is closed as "wontfix" with a + request for the reporter to start a discussion on the |django-developers| + mailing list if they feel differently from the rationale provided by the + person who closed the ticket. Other times, a mailing list discussion + precedes the decision to close a ticket. Always use the mailing list to + get a consensus before reopening tickets closed as "wontfix". * duplicate Used when another ticket covers the same issue. By closing duplicate @@ -332,8 +329,8 @@ A ticket can be resolved in a number of ways: If you believe that the ticket was closed in error -- because you're still having the issue, or it's popped up somewhere else, or the triagers have made a mistake -- please reopen the ticket and provide further information. -Again, please do not reopen tickets that have been marked as "wontfix" by core -developers and bring the issue to |django-developers| instead. +Again, please do not reopen tickets that have been marked as "wontfix" and +bring the issue to |django-developers| instead. .. _how-can-i-help-with-triaging: @@ -343,17 +340,14 @@ How can I help with triaging? The triage process is primarily driven by community members. Really, **ANYONE** can help. -Core developers may provide feedback on issues they're familiar with, or make -decisions on controversial ones, but they aren't responsible for triaging -tickets in general. - To get involved, start by `creating an account on Trac`_. If you have an account but have forgotten your password, you can reset it using the `password reset page`_. Then, you can help out by: -* Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate." +* Closing "Unreviewed" tickets as "invalid", "worksforme", or "duplicate", or + "wontfix". * Closing "Unreviewed" tickets as "needsinfo" when the description is too sparse to be actionable, or when they're feature requests requiring a @@ -396,18 +390,13 @@ Then, you can help out by: However, we do ask the following of all general community members working in the ticket database: -* Please **don't** close tickets as "wontfix." The core developers will - make the final determination of the fate of a ticket, usually after - consultation with the community. - * Please **don't** promote your own tickets to "Ready for checkin". You may mark other people's tickets which you've reviewed as "Ready for checkin", but you should get at minimum one other community member to review a patch that you submit. -* Please **don't** reverse a decision that has been made by a :doc:`core - developer`. If you disagree with a decision that - has been made, please post a message to |django-developers|. +* Please **don't** reverse a decision without posting a message to + |django-developers| to find consensus. * If you're unsure if you should be making a change, don't make the change but instead leave a comment with your concerns on the ticket, diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index ce1d6403a8..cbda36075d 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -249,9 +249,9 @@ the "Triage Stage" on the corresponding Trac ticket to "Ready for checkin". If you've left comments for improvement on the pull request, please tick the appropriate flags on the Trac ticket based on the results of your review: "Patch needs improvement", "Needs documentation", and/or "Needs tests". As time -and interest permits, core developers do final reviews of "Ready for checkin" +and interest permits, committers do final reviews of "Ready for checkin" tickets and will either commit the patch or bump it back to "Accepted" if -further works need to be done. If you're looking to become a core developer, +further works need to be done. If you're looking to become a committer, doing thorough reviews of patches is a great way to earn trust. Looking for a patch to review? Check out the "Patches needing review" section @@ -296,8 +296,7 @@ All code changes guidelines? Are there any ``flake8`` errors? * If the change is backwards incompatible in any way, is there a note in the release notes (``docs/releases/A.B.txt``)? -* Is Django's test suite passing? Ask in ``#django-dev`` for a core dev - to build the pull request against our continuous integration server. +* Is Django's test suite passing? All tickets ----------- diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index 7cea064b2a..85ca6dfc85 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -3,7 +3,7 @@ Working with Git and GitHub =========================== This section explains how the community can contribute code to Django via pull -requests. If you're interested in how core developers handle them, see +requests. If you're interested in how committers handle them, see :doc:`../committing-code`. Below, we are going to show how to create a GitHub pull request containing the