diff --git a/.github/workflows/new_contributor_pr.yml b/.github/workflows/new_contributor_pr.yml index 3e0119ebdc..aa36db75a4 100644 --- a/.github/workflows/new_contributor_pr.yml +++ b/.github/workflows/new_contributor_pr.yml @@ -18,7 +18,7 @@ jobs: pr-message: | Hello! Thank you for your contribution 💪 - As it's your first contribution be sure to check out the [patch review checklist](https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/submitting-patches/#patch-review-checklist). + As it's your first contribution be sure to check out the [contribution checklist](https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/submitting-patches/#patch-review-checklist). If you're fixing a ticket [from Trac](https://code.djangoproject.com/) make sure to set the _"Has patch"_ flag and include a link to this PR in the ticket! diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 4b2ab36366..3aba3d9f71 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -6,9 +6,9 @@ As an open source project, Django welcomes contributions of many forms. Examples of contributions include: -* Code patches +* Code contributions * Documentation improvements -* Bug reports and patch reviews +* Bug reports and code reviews Extensive contribution guidelines are available in the repository at ``docs/internals/contributing/``, or online at: @@ -21,9 +21,9 @@ Trac tickets will be closed!** `Please file a ticket`__ to suggest changes. __ https://code.djangoproject.com/newticket Django uses Trac to keep track of bugs, feature requests, and associated -patches because GitHub doesn't provide adequate tooling for its community. -Patches can be submitted as pull requests, but if you don't file a ticket, -it's unlikely that we'll notice your contribution. +code contributions. Code contributions can be submitted as pull requests, +but if you don't file a ticket, it's unlikely that we'll notice your +contribution. Code of Conduct =============== diff --git a/docs/internals/_images/triage_process.svg b/docs/internals/_images/triage_process.svg index 6fbf1cbcc7..9babf2f4e8 100644 --- a/docs/internals/_images/triage_process.svg +++ b/docs/internals/_images/triage_process.svg @@ -264,7 +264,7 @@ - The ticket has a patch which applies cleanly and includes all + The ticket has a pull request which includes all needed tests and docs. A merger can commit it as is. diff --git a/docs/internals/contributing/bugs-and-features.txt b/docs/internals/contributing/bugs-and-features.txt index c59f79e6b8..ca1ff89891 100644 --- a/docs/internals/contributing/bugs-and-features.txt +++ b/docs/internals/contributing/bugs-and-features.txt @@ -71,7 +71,7 @@ are a few additional guidelines to follow: 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 +* If you're proposing a change that impacts 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. diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index 91c6d21beb..fd4eccd687 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -11,8 +11,7 @@ contribute code to Django, look at :doc:`writing-code/working-with-git` instead. Handling pull requests ====================== -Since Django is hosted on GitHub, patches are provided in the form of pull -requests. +Django is hosted on GitHub and uses pull requests (PRs) for contributions. When committing a pull request, make sure each individual commit matches the commit guidelines described below. Contributors are expected to provide the @@ -74,10 +73,10 @@ line. When rewriting the commit history of a pull request, the goal is to make Django's commit history as usable as possible: -* If a patch contains back-and-forth commits, then rewrite those into one. - For example, if a commit adds some code and a second commit fixes stylistic - issues introduced in the first commit, those commits should be squashed - before merging. +* If a contribution contains back-and-forth commits, then rewrite those into + one. For example, if a commit adds some code and a second commit fixes + stylistic issues introduced in the first commit, those commits should be + squashed before merging. * Separate changes to different commits by logical grouping: if you do a stylistic cleanup at the same time as you do other changes to a file, @@ -89,7 +88,7 @@ Django's commit history as usable as possible: * Tests should pass and docs should build after each commit. Neither the tests nor the docs should emit warnings. -* Trivial and small patches usually are best done in one commit. Medium to +* Trivial and small changes usually are best done in one commit. Medium to large work may be split into multiple commits if it makes sense. Practicality beats purity, so it is up to each merger to decide how much diff --git a/docs/internals/contributing/new-contributors.txt b/docs/internals/contributing/new-contributors.txt index c728abccd6..73162aadfd 100644 --- a/docs/internals/contributing/new-contributors.txt +++ b/docs/internals/contributing/new-contributors.txt @@ -27,39 +27,39 @@ Triage tickets If an `unreviewed ticket`_ reports a bug, try and reproduce it. If you can reproduce it and it seems valid, make a note that you confirmed the bug and accept the ticket. Make sure the ticket is filed under the correct component -area. Consider writing a patch that adds a test for the bug's behavior, even if -you don't fix the bug itself. See more at :ref:`how-can-i-help-with-triaging` +area. Consider writing a test for the bug's behavior, even if you don't fix the +bug itself. See more at :ref:`how-can-i-help-with-triaging` -Review patches of accepted tickets ----------------------------------- +Review pull requests of accepted tickets +---------------------------------------- This will help you build familiarity with the codebase and processes. Mark the -appropriate flags if a patch needs docs or tests. Look through the changes a -patch makes, and keep an eye out for syntax that is incompatible with older but -still supported versions of Python. :doc:`Run the tests +appropriate flags if a pull request needs docs or tests. Look through the +files changed in the PR, and keep an eye out for syntax that is incompatible +with older but still supported versions of Python. :doc:`Run the tests ` and make sure they pass. Where possible and relevant, try them out on a database other than SQLite. Leave comments and feedback! -Keep old patches up-to-date ---------------------------- +Keep old pull requests up-to-date +--------------------------------- -Oftentimes the codebase will change between a patch being submitted and the -time it gets reviewed. Make sure it still applies cleanly and functions as -expected. Updating a patch is both useful and important! See more on -:doc:`writing-code/submitting-patches`. +Oftentimes the codebase will change between a pull request being submitted and +the time it gets reviewed. Make sure there are no merge conflicts and that the +code still functions as expected. Updating a pull request is both useful and +important! See more on :doc:`writing-code/submitting-patches`. Write some documentation ------------------------ Django's documentation is great but it can always be improved. Did you find a typo? Do you think that something should be clarified? Go ahead and suggest a -documentation patch! See also the guide on :doc:`writing-documentation`. +documentation change! See also the guide on :doc:`writing-documentation`. .. 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 pull requests as suggested above. .. _reports page: https://code.djangoproject.com/wiki/Reports @@ -118,7 +118,7 @@ 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 +ticket is correct" or "this pull request 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 any one person. We can't do it without **you**! @@ -141,25 +141,26 @@ wayside ends up doing more harm than good. Be rigorous ----------- -When we say ":pep:`8`, and must have docs and tests", we mean it. If a patch -doesn't have docs and tests, there had better be a good reason. Arguments like -"I couldn't find any existing tests of this feature" don't carry much weight. -While it may be true, that means you have the extra-important job of writing -the very first tests for that feature, not that you get a pass from writing -tests altogether. +When we say ":pep:`8`, and must have docs and tests", we mean it. If a pull +request doesn't have docs and tests, there had better be a good reason. +Arguments like "I couldn't find any existing tests of this feature" don't carry +much weight. While it may be true, that means you have the extra-important job +of writing the very first tests for that feature, not that you get a pass from +writing tests altogether. Be patient ---------- -It's not always easy for your ticket or your patch to be reviewed quickly. This -isn't personal. There are a lot of tickets and pull requests to get through. +It's not always easy for your ticket or pull request to be reviewed quickly. +This isn't personal. There are a lot of tickets and pull requests to get +through. -Keeping your patch up to date is important. Review the ticket on Trac to ensure -that the *Needs tests*, *Needs documentation*, and *Patch needs improvement* -flags are unchecked once you've addressed all review comments. +Keeping your pull request up to date is important. Review the ticket on Trac to +ensure that the *Needs tests*, *Needs documentation*, and *Patch needs +improvement* flags are unchecked once you've addressed all review comments. Remember that Django has an eight-month release cycle, so there's plenty of -time for your patch to be reviewed. +time for your contribution to be reviewed. Finally, a well-timed reminder can help. See :ref:`contributing code FAQ ` for ideas here. diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index 7987d63e9a..d734b246de 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -71,7 +71,7 @@ By way of example, here we see the lifecycle of an average ticket: * 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. + pull request could be improved. * Alice updates the pull request, adding tests (but not changing the implementation). She removes the two flags. @@ -114,22 +114,23 @@ 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 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. + The ticket is valid, but no one has submitted a pull request for it yet. + Often this 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 pull request will be + accepted for that feature. Seek more feedback before writing an extensive + contribution if you are in doubt. * **Accepted + Has Patch** 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. + checking out the pull request and trying it out, verifying that it contains + tests and docs, checking that all the automated tests on the pull request are + passing, and leaving feedback. * **Accepted + Has Patch + Needs ...** @@ -142,11 +143,11 @@ 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 +who submitted the pull request and found to meet all the requirements for a 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 +There are a lot of pull requests. It can take a while for yours to get reviewed. See the :ref:`contributing code FAQ` for some ideas here. @@ -158,8 +159,8 @@ 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 -consider adding someday to the framework if an excellent patch is submitted. -They are not a high priority. +consider adding someday to the framework if an excellent contribution is +submitted. They are not a high priority. Other triage attributes ======================= @@ -174,28 +175,27 @@ 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. +Patch needs improvement) apply only if a pull request has been supplied. Needs documentation ------------------- -This flag is used for tickets with patches that need associated -documentation. Complete documentation of features is a prerequisite -before we can check them into the codebase. +This flag is used for tickets with pull requests that need associated +documentation. Complete documentation of features is a prerequisite before we +can check them into the codebase. Needs tests ----------- -This flags the patch as needing associated unit tests. Again, this -is a required part of a valid contribution. +This flags the pull request as needing associated unit tests. Again, this is a +required part of a valid contribution. Patch needs improvement ----------------------- 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. +ready for checkin. This could mean the pull request has merge conflicts, there +is a flaw in the implementation, or that the code doesn't meet our standards. Easy pickings ------------- @@ -296,7 +296,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 once a patch has been rolled into Django and the issue is fixed. + Used once a commit has been merged and the issue is fixed. * invalid Used if the ticket is found to be incorrect. This means that the @@ -396,7 +396,7 @@ the ticket database: * Please **don't** promote your own tickets to "Ready for checkin". You may mark other people's tickets that you've reviewed as "Ready for checkin", but you should get at minimum one other community member to - review a patch that you submit. + review a pull request that you submit. * Please **don't** reverse a decision without posting a message to the `Django Forum`_ or |django-developers| to find consensus. diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt index 20605aef56..73042ff5b7 100644 --- a/docs/internals/contributing/writing-code/coding-style.txt +++ b/docs/internals/contributing/writing-code/coding-style.txt @@ -489,7 +489,7 @@ Miscellaneous silence the flake8 warning. * Systematically remove all trailing whitespaces from your code as those - add unnecessary bytes, add visual clutter to the patches and can also + add unnecessary bytes, add visual clutter to the ``git diff`` and can also occasionally cause unnecessary merge conflicts. Some IDE's can be configured to automatically remove them and most VCS tools can be set to highlight them in diff outputs. @@ -497,7 +497,7 @@ Miscellaneous * Please don't put your name in the code you contribute. Our policy is to keep contributors' names in the ``AUTHORS`` file distributed with Django -- not scattered throughout the codebase itself. Feel free to include a - change to the ``AUTHORS`` file in your patch if you make more than a + change to the ``AUTHORS`` file in your contribution if you make more than a single trivial change. JavaScript style diff --git a/docs/internals/contributing/writing-code/index.txt b/docs/internals/contributing/writing-code/index.txt index 72cc264524..1835306996 100644 --- a/docs/internals/contributing/writing-code/index.txt +++ b/docs/internals/contributing/writing-code/index.txt @@ -25,7 +25,7 @@ our documentation also contains useful guidance on specific topics: .. toctree:: :maxdepth: 1 - How to submit a patch to Django for new and/or fixed behavior + How to submit a pull request to Django for new and/or fixed behavior How to write and run tests How to run Django's unit tests How to work with Git and GitHub diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt index 25165206f0..41328b4ae5 100644 --- a/docs/internals/contributing/writing-code/javascript.txt +++ b/docs/internals/contributing/writing-code/javascript.txt @@ -30,10 +30,8 @@ Code style ``$(selector).click(func)``. This makes it easier for projects to extend Django's default behavior with JavaScript. -.. _javascript-patches: - -JavaScript patches -================== +jQuery and performance +====================== Django's admin system leverages the jQuery framework to increase the capabilities of the admin interface. In conjunction, there is an emphasis on diff --git a/docs/internals/contributing/writing-code/submitting-patches.txt b/docs/internals/contributing/writing-code/submitting-patches.txt index c3d0e1745f..9b94f4c60e 100644 --- a/docs/internals/contributing/writing-code/submitting-patches.txt +++ b/docs/internals/contributing/writing-code/submitting-patches.txt @@ -12,8 +12,8 @@ Typo fixes and trivial documentation changes ============================================ If you are fixing a really trivial issue, for example changing a word in the -documentation, the preferred way to provide the patch is using GitHub pull -requests without a Trac ticket. +documentation, the preferred way is to open a pull request on GitHub without a +Trac ticket. See the :doc:`working-with-git` for more details on how to use pull requests. @@ -112,7 +112,7 @@ requirements: 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. + discussions in the future. * If the code adds a new feature, or modifies the behavior of an existing feature, the change should also contain documentation. @@ -147,7 +147,7 @@ Regardless of the way you submit your work, follow these steps. Contributions which require community feedback ============================================== -A wider community discussion is required when a patch introduces new Django +A wider community discussion is required when a change introduces new Django functionality and makes some sort of design decision. This is especially important if the approach involves a :ref:`deprecation ` or introduces breaking changes. @@ -306,14 +306,14 @@ In each :term:`feature release `, all JavaScript contributions ======================== -For information on JavaScript contributions, see the :ref:`javascript-patches` +For information on JavaScript contributions, see the :doc:`javascript` documentation. -Optimization patches +Optimization changes ==================== -Patches aiming to deliver a performance improvement should provide benchmarks -showing the before and after impact of the patch and sharing the commands for +Changes aiming to deliver a performance improvement should provide benchmarks +showing the before and after impact of the change and sharing the commands for reviewers to reproduce. .. _django-asv-benchmarks: @@ -349,12 +349,14 @@ If you're looking to become a member of the `triage & review team `_, 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 for a pull request to review? Check out the "Patches needing review" +section of the `Django Development Dashboard`_. Looking to get your pull request reviewed? Ensure the Trac flags on the ticket are set so that the ticket appears in that queue. +.. _Django Development Dashboard: https://dashboard.djangoproject.com/ + Documentation ------------- @@ -405,8 +407,8 @@ All tickets * Is the pull request a single squashed commit with a message that follows our :ref:`commit message format `? -* Are you the patch author and a new contributor? Please add yourself to the - :source:`AUTHORS` file and submit a `Contributor License Agreement`_. +* Are you the pull request author and a new contributor? Please add yourself to + the :source:`AUTHORS` file and submit a `Contributor License Agreement`_. * Does this have an accepted ticket on Trac? All contributions require a ticket unless the :ref:`change is considered trivial `. diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index 3641bfb8cc..faa685e9b4 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -129,7 +129,7 @@ Running the JavaScript tests Django includes a set of :ref:`JavaScript unit tests ` for functions in certain contrib apps. The JavaScript tests aren't run by default using ``tox`` because they require ``Node.js`` to be installed and aren't -necessary for the majority of patches. To run the JavaScript tests using +necessary for the majority of contributions. To run the JavaScript tests using ``tox``: .. console:: diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index 579543f876..3860a240e7 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -281,12 +281,12 @@ Your pull request should now contain the new commit too. Note that the merger is likely to squash the review commit into the previous commit when committing the code. -Working on a patch -================== +Testing a pull request locally +============================== -One of the ways that developers can contribute to Django is by reviewing -patches. Those patches will typically exist as pull requests on GitHub and -can be easily integrated into your local repository: +One of the ways that developers can contribute to Django is by reviewing and +testing pull requests. Pull requests can be easily integrated into your local +repository: .. code-block:: shell @@ -295,7 +295,7 @@ can be easily integrated into your local repository: This will create a new branch and then apply the changes from the pull request to it. At this point you can run the tests or do anything else you need to -do to investigate the quality of the patch. +do to investigate the quality of the pull request. For more detail on working with pull requests see the :ref:`guidelines for mergers `. diff --git a/docs/internals/git.txt b/docs/internals/git.txt index 7329fe0bbc..617ab198b7 100644 --- a/docs/internals/git.txt +++ b/docs/internals/git.txt @@ -80,7 +80,7 @@ If you're going to be working on Django's code (say, to fix a bug or develop a new feature), you can probably stop reading here and move over to :doc:`the documentation for contributing to Django `, which covers things like the preferred -coding style and how to generate and submit a patch. +coding style and how to submit a pull request. Stable branches =============== diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt index a845faf330..c43f798610 100644 --- a/docs/internals/release-process.txt +++ b/docs/internals/release-process.txt @@ -131,9 +131,9 @@ page for the current state of support for each version. * The current development branch ``main`` will get new features and bug fixes requiring non-trivial refactoring. -* Patches applied to the main branch must also be applied to the last feature - release branch, to be released in the next patch release of that feature - series, when they fix critical problems: +* Commits from the main branch must also be applied to the last feature release + branch, to be released in the next patch release of that feature series, when + they fix critical problems: * Security issues.