diff --git a/docs/internals/contributing/localizing.txt b/docs/internals/contributing/localizing.txt index 296f612332..112a74dd9e 100644 --- a/docs/internals/contributing/localizing.txt +++ b/docs/internals/contributing/localizing.txt @@ -59,13 +59,14 @@ the date, time and numbers formatting particularities of your locale. See :doc:`/topics/i18n/formatting` for details. The format files aren't managed by the use of Transifex. To change them, you -must :doc:`create a patch` against the -Django source tree, as for any code change: +must: -* Create a diff against the current Git main branch. +* :doc:`Create a pull request` against the + Django Git ``main`` branch, as for any code change. * Open a ticket in Django's ticket system, set its ``Component`` field to - ``Translations``, and attach the patch to it. + ``Translations``, set the "has patch" flag, and include the link to the pull + request. .. _Transifex: https://www.transifex.com/ .. _Django project page: https://app.transifex.com/django/django/ diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index 7473405007..852219c96c 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -35,8 +35,8 @@ 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 patches, but those patches don't meet all the requirements of a -:ref:`good patch`. +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. @@ -56,7 +56,7 @@ Since a picture is worth a thousand words, let's start there: We've got two roles in this diagram: * Mergers: people with commit access who are responsible for making the - final decision to merge a patch. + final decision to merge a change. * Ticket triagers: anyone in the Django community who chooses to become involved in Django's development process. Our Trac installation @@ -115,18 +115,18 @@ Beyond that there are several considerations: * **Accepted + No Flags** The ticket is valid, but no one has submitted a patch for it yet. Often this - means you could safely start writing a patch for it. This is generally more + 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 patch if you are in doubt. + feedback before writing an extensive contribution if you are in doubt. * **Accepted + Has Patch** - The ticket is waiting for people to review the supplied patch. This means + The ticket is waiting for people to review the supplied solution. This means downloading the patch and trying it out, verifying that it contains tests and docs, running the test suite with the included patch, and leaving feedback on the ticket. @@ -143,7 +143,7 @@ Ready For Checkin The ticket was reviewed by any member of the community other than the person who supplied the patch and found to meet all the requirements for a -commit-ready patch. A :ref:`merger ` now needs to give the patch +commit-ready contribution. A :ref:`merger ` now needs to give a final review prior to being committed. There are a lot of pull requests. It can take a while for your patch to get @@ -169,9 +169,9 @@ A number of flags, appearing as checkboxes in Trac, can be set on a ticket: Has patch --------- -This means the ticket has an associated -:doc:`patch`. These will be reviewed -to see if the patch is "good". +This means the ticket has an associated solution. These will be reviewed to +ensure they adhere to the :doc:`documented guidelines +`. The following three fields (Needs documentation, Needs tests, Patch needs improvement) apply only if a patch has been supplied. @@ -187,12 +187,12 @@ Needs tests ----------- This flags the patch as needing associated unit tests. Again, this -is a required part of a valid patch. +is a required part of a valid contribution. Patch needs improvement ----------------------- -This flag means that although the ticket *has* a patch, it's not quite +This flag means that although the ticket *has* a solution, it's not quite ready for checkin. This could mean the patch no longer applies cleanly, there is a flaw in the implementation, or that the code doesn't meet our standards. @@ -200,7 +200,7 @@ doesn't meet our standards. Easy pickings ------------- -Tickets that would require small, easy, patches. +Tickets that would require small, easy, changes. Type ---- @@ -374,7 +374,7 @@ Then, you can help out by: you should raise it for discussion (referencing the relevant tickets) on the `Django Forum`_ or |django-developers|. -* Verify if patches submitted by other users are correct. If they are correct +* Verify if solutions submitted by others are correct. If they are correct and also contain appropriate documentation and tests then move them to the "Ready for Checkin" stage. If they are not correct then leave a comment to explain why and set the corresponding flags ("Patch needs improvement", @@ -383,7 +383,7 @@ Then, you can help out by: .. note:: The `Reports page`_ contains links to many useful Trac queries, including - several that are useful for triaging tickets and reviewing patches as + several that are useful for triaging tickets and reviewing proposals as suggested above. You can also find more :doc:`new-contributors`. diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index 72c986cfc7..11a96eb911 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -1,10 +1,10 @@ -================== -Submitting patches -================== +======================== +Submitting contributions +======================== -We're always grateful for patches to Django's code. Indeed, bug reports -with associated patches will get fixed *far* more quickly than those -without patches. +We're always grateful for contributions to Django's code. Indeed, bug reports +with associated contributions will get fixed *far* more quickly than those +without a solution. Typo fixes and trivial documentation changes ============================================ @@ -52,7 +52,7 @@ and time availability), claim it by following these steps: .. note:: The Django software foundation requests that anyone contributing more than - a trivial patch to Django sign and submit a `Contributor License + a trivial change to Django sign and submit a `Contributor License Agreement`_, this ensures that the Django Software Foundation has clear license to all contributions allowing for a clear license for all users. @@ -86,35 +86,32 @@ Going through the steps of claiming tickets is overkill in some cases. In the case of small changes, such as typos in the documentation or small bugs that will only take a few minutes to fix, you don't need to jump through the -hoops of claiming tickets. Submit your patch directly and you're done! +hoops of claiming tickets. Submit your changes directly and you're done! It is *always* acceptable, regardless whether someone has claimed it or not, to -submit patches to a ticket if you happen to have a patch ready. +link proposals to a ticket if you happen to have the changes ready. .. _patch-style: -Patch style -=========== +Contribution style +================== Make sure that any contribution you do fulfills at least the following requirements: * The code required to fix a problem or add a feature is an essential part - of a patch, but it is not the only part. A good patch should also include a + of a solution, but it is not the only part. A good fix should also include a :doc:`regression test ` to validate the behavior that has been fixed and to prevent the problem from arising again. Also, if some tickets are relevant to the code that you've written, mention the ticket numbers in some comments in the test so that one can easily trace back the relevant discussions after your patch gets committed, and the tickets get closed. -* If the code associated with a patch adds a new feature, or modifies - behavior of an existing feature, the patch should also contain - documentation. +* If the code adds a new feature, or modifies the behavior of an existing + feature, the change should also contain documentation. When you think your work is ready to be reviewed, send :doc:`a GitHub pull -request `. Please review the patch yourself using our -:ref:`patch review checklist ` first. - +request `. If you can't send a pull request for some reason, you can also use patches in Trac. When using this style, follow these guidelines. @@ -129,7 +126,7 @@ Trac. When using this style, follow these guidelines. Regardless of the way you submit your work, follow these steps. -* Make sure your code fulfills the requirements in our :ref:`patch review +* Make sure your code fulfills the requirements in our :ref:`contribution checklist `. * Check the "Has patch" box on the ticket and make sure the "Needs @@ -140,17 +137,18 @@ Regardless of the way you submit your work, follow these steps. .. _ticket tracker: https://code.djangoproject.com/ .. _Development dashboard: https://dashboard.djangoproject.com/ -Non-trivial patches -=================== +Non-trivial contributions +========================= -A "non-trivial" patch is one that is more than a small bug fix. It's a patch -that introduces Django functionality and makes some sort of design decision. +A "non-trivial" contribution is one that is more than a small bug fix. It's a +change that introduces new Django functionality and makes some sort of design +decision. -If you provide a non-trivial patch, include evidence that alternatives have +If you provide a non-trivial change, include evidence that alternatives have been discussed on the `Django Forum`_ or |django-developers| list. -If you're not sure whether your patch should be considered non-trivial, ask on -the ticket for opinions. +If you're not sure whether your contribution should be considered non-trivial, +ask on the ticket for opinions. .. _Django Forum: https://forum.djangoproject.com/ @@ -253,15 +251,15 @@ Once you have completed these steps, you are finished with the deprecation. In each :term:`feature release `, all ``RemovedInDjangoXXWarning``\s matching the new version are removed. -JavaScript patches -================== +JavaScript contributions +======================== -For information on JavaScript patches, see the :ref:`javascript-patches` +For information on JavaScript contributions, see the :ref:`javascript-patches` documentation. .. _patch-review-checklist: -Patch review checklist +Contribution checklist ====================== Use this checklist to review a pull request. If you are reviewing a pull @@ -271,14 +269,15 @@ 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, mergers 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 merger, doing thorough reviews -of patches is a great way to earn trust. +and will either commit the changes or bump it back to "Accepted" if further +work needs to be done. If you're looking to become a merger, doing thorough +reviews of contributions is a great way to earn trust. Looking for a patch to review? Check out the "Patches needing review" section of the `Django Development Dashboard `_. -Looking to get your patch reviewed? Ensure the Trac flags on the ticket are -set so that the ticket appears in that queue. + +Looking to get your pull request reviewed? Ensure the Trac flags on the ticket +are set so that the ticket appears in that queue. Documentation -------------