Replaced usage of "patch" with more precise terms in faq, howto, and intro docs.

Author: avallbona

docs/faq/contributing.txt

@@ -10,8 +10,8 @@ How can I get started contributing code to Django?
 Thanks for asking! We've written an entire document devoted to this question.
 It's titled :doc:`Contributing to Django </internals/contributing/index>`.
 
-I submitted a bug fix in the ticket system several weeks ago. Why are you ignoring my patch?
-============================================================================================
+I submitted a bug fix several weeks ago. Why are you ignoring my contribution?
+==============================================================================
 
 Don't worry: We're not ignoring you!
 
@@ -34,21 +34,21 @@ that area of the code, to understand the problem and verify the fix:
   database, are those instructions clear enough even for someone not
   familiar with it?
 
-* If there are several patches attached to the ticket, is it clear what
-  each one does, which ones can be ignored and which matter?
+* If there are several branches linked to the ticket, is it clear what each one
+  does, which ones can be ignored and which matter?
 
-* Does the patch include a unit test? If not, is there a very clear
+* Does the change include a unit test? If not, is there a very clear
   explanation why not? A test expresses succinctly what the problem is,
-  and shows that the patch actually fixes it.
+  and shows that the branch actually fixes it.
 
-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
+If your contribution is not suitable for inclusion in Django, we won't ignore
+it -- we'll 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 team of a patch I care about?
-=============================================================
+When and how might I remind the team of a change I care about?
+==============================================================
 
-A polite, well-timed message to the mailing list is one way to get attention.
+A polite, well-timed message in the forum/branch 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 right before a release deadline, you're not likely to get the
 sort of attention you require.
@@ -68,11 +68,11 @@ issue over and over again. 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!
-===================================================================
+But I've reminded you several times and you keep ignoring my contribution!
+==========================================================================
 
-Seriously - we're not ignoring you. If your patch stands no chance of
-inclusion in Django, we'll close the ticket. For all the other tickets, we
+Seriously - we're not ignoring you. If your contribution is not suitable for
+inclusion in Django, we will close the ticket. For all the other tickets, we
 need to prioritize our efforts, which means that some tickets will be
 addressed before others.
 
@@ -83,7 +83,7 @@ are edge cases.
 
 Another reason that a bug might be ignored for a while is if the bug is a
 symptom of a larger problem. While we can spend time writing, testing and
-applying lots of little patches, sometimes the right solution is to rebuild. If
+applying lots of little changes, sometimes the right solution is to rebuild. If
 a rebuild or refactor of a particular component has been proposed or is
 underway, you may find that bugs affecting that component will not get as much
 attention. Again, this is a matter of prioritizing scarce resources. By

docs/howto/windows.txt

@@ -6,7 +6,7 @@ This document will guide you through installing Python 3.12 and Django on
 Windows. It also provides instructions for setting up a virtual environment,
 which makes it easier to work on Python projects. This is meant as a beginner's
 guide for users working on Django projects and does not reflect how Django
-should be installed when developing patches for Django itself.
+should be installed when developing changes for Django itself.
 
 The steps in this guide have been tested with Windows 10. In other
 versions, the steps would be similar. You will need to be familiar with using

docs/index.txt

@@ -27,7 +27,7 @@ Are you new to Django or to programming? This is the place to start!
 
 * **Advanced Tutorials:**
   :doc:`How to write reusable apps <intro/reusable-apps>` |
-  :doc:`Writing your first patch for Django <intro/contributing>`
+  :doc:`Writing your first contribution to Django <intro/contributing>`
 
 Getting help
 ============

docs/intro/contributing.txt

@@ -1,6 +1,6 @@
-===================================
-Writing your first patch for Django
-===================================
+==========================================
+Writing your first contribution for Django
+==========================================
 
 Introduction
 ============
@@ -52,16 +52,16 @@ __ https://web.libera.chat/#django-dev
 What does this tutorial cover?
 ------------------------------
 
-We'll be walking you through contributing a patch to Django for the first time.
+We'll be walking you through contributing to Django for the first time.
 By the end of this tutorial, you should have a basic understanding of both the
 tools and the processes involved. Specifically, we'll be covering the following:
 
 * Installing Git.
 * Downloading a copy of Django's development version.
 * Running Django's test suite.
-* Writing a test for your patch.
-* Writing the code for your patch.
-* Testing your patch.
+* Writing a test for your changes.
+* Writing the code for your changes.
+* Testing your changes.
 * Submitting a pull request.
 * Where to look for more information.
 
@@ -91,7 +91,7 @@ Installing Git
 ==============
 
 For this tutorial, you'll need Git installed to download the current
-development version of Django and to generate patch files for the changes you
+development version of Django and to generate a branch for the changes you
 make.
 
 To check whether or not you have Git installed, enter ``git`` into the command
@@ -178,7 +178,7 @@ Go ahead and install the previously cloned copy of Django:
 
 The installed version of Django is now pointing at your local copy by installing
 in editable mode. You will immediately see any changes you make to it, which is
-of great help when writing your first patch.
+of great help when writing your first contribution.
 
 Creating projects with a local copy of Django
 ---------------------------------------------
@@ -188,8 +188,8 @@ have to create a new virtual environment, :ref:`install the previously cloned
 local copy of Django in editable mode <intro-contributing-install-local-copy>`,
 and create a new Django project outside of your local copy of Django. You will
 immediately see any changes you make to Django in your new project, which is
-of great help when writing your first patch, especially if testing any changes
-to the UI.
+of great help when writing your first contribution, especially if testing
+any changes to the UI.
 
 You can follow the :doc:`tutorial</intro/tutorial01>` for help in creating a
 Django project.
@@ -279,8 +279,8 @@ imaginary details:
 
 We'll now implement this feature and associated tests.
 
-Creating a branch for your patch
-================================
+Creating a branch
+=================
 
 Before making any changes, create a new branch for the ticket:
 
@@ -295,19 +295,19 @@ won't affect the main copy of the code that we cloned earlier.
 Writing some tests for your ticket
 ==================================
 
-In most cases, for a patch to be accepted into Django it has to include tests.
-For bug fix patches, this means writing a regression test to ensure that the
-bug is never reintroduced into Django later on. A regression test should be
-written in such a way that it will fail while the bug still exists and pass
-once the bug has been fixed. For patches containing new features, you'll need
-to include tests which ensure that the new features are working correctly.
-They too should fail when the new feature is not present, and then pass once it
-has been implemented.
+In most cases, for a contribution to be accepted into Django it has to include
+tests. For bug fix contributions, this means writing a regression test to
+ensure that  the bug is never reintroduced into Django later on. A regression
+test should be written in such a way that it will fail while the bug still
+exists and pass once the bug has been fixed. For contributions containing new
+features, you'll need to include tests which ensure that the new features are
+working correctly. They too should fail when the new feature is not present,
+and then pass once it has been implemented.
 
 A good way to do this is to write your new tests first, before making any
 changes to the code. This style of development is called
 `test-driven development`__ and can be applied to both entire projects and
-single patches. After writing your tests, you then run them to make sure that
+single changes. After writing your tests, you then run them to make sure that
 they do indeed fail (since you haven't fixed that bug or added that feature
 yet). If your new tests don't fail, you'll need to fix them so that they do.
 After all, a regression test that passes regardless of whether a bug is present
@@ -398,7 +398,7 @@ function to the correct file.
 Running Django's test suite for the second time
 ===============================================
 
-Once you've verified that your patch and your test are working correctly, it's
+Once you've verified that your changes and test are working correctly, it's
 a good idea to run the entire Django test suite to verify that your change
 hasn't introduced any bugs into other areas of Django. While successfully
 passing the entire test suite doesn't guarantee your code is bug free, it does
@@ -450,7 +450,7 @@ preview the HTML that will be generated.
 Previewing your changes
 =======================
 
-Now it's time to go through all the changes made in our patch. To stage all the
+Now it's time to review the changes made in the branch. To stage all the
 changes ready for commit, run:
 
 .. console::
@@ -528,12 +528,11 @@ Use the arrow keys to move up and down.
     +    def test_make_toast(self):
     +        self.assertEqual(make_toast(), 'toast')
 
-When you're done previewing the patch, hit the ``q`` key to return to the
-command line. If the patch's content looked okay, it's time to commit the
-changes.
+When you're done previewing the changes, hit the ``q`` key to return to the
+command line. If the diff looked okay, it's time to commit the changes.
 
-Committing the changes in the patch
-===================================
+Committing the changes
+======================
 
 To commit the changes:
 
@@ -551,7 +550,7 @@ message guidelines <committing-guidelines>` and write a message like:
 Pushing the commit and making a pull request
 ============================================
 
-After committing the patch, send it to your fork on GitHub (substitute
+After committing the changes, send it to your fork on GitHub (substitute
 "ticket_99999" with the name of your branch if it's different):
 
 .. console::
@@ -563,7 +562,7 @@ You can create a pull request by visiting the `Django GitHub page
 recently pushed branches". Click "Compare & pull request" next to it.
 
 Please don't do it for this tutorial, but on the next page that displays a
-preview of the patch, you would click "Create pull request".
+preview of the changes, you would click "Create pull request".
 
 Next steps
 ==========
@@ -578,14 +577,14 @@ codebase.
 More information for new contributors
 -------------------------------------
 
-Before you get too into writing patches for Django, there's a little more
+Before you get too into contributing to Django, there's a little more
 information on contributing that you should probably take a look at:
 
 * You should make sure to read Django's documentation on
-  :doc:`claiming tickets and submitting patches
+  :doc:`claiming tickets and submitting pull requests
   </internals/contributing/writing-code/submitting-patches>`.
   It covers Trac etiquette, how to claim tickets for yourself, expected
-  coding style for patches, and many other important details.
+  coding style (both for code and docs), and many other important details.
 * First time contributors should also read Django's :doc:`documentation
   for first time contributors</internals/contributing/new-contributors/>`.
   It has lots of good advice for those of us who are new to helping out
@@ -600,19 +599,19 @@ Finding your first real ticket
 ------------------------------
 
 Once you've looked through some of that information, you'll be ready to go out
-and find a ticket of your own to write a patch for. Pay special attention to
+and find a ticket of your own to contribute to. Pay special attention to
 tickets with the "easy pickings" criterion. These tickets are often much
 simpler in nature and are great for first time contributors. Once you're
-familiar with contributing to Django, you can move on to writing patches for
-more difficult and complicated tickets.
+familiar with contributing to Django, you can start working on more difficult
+and complicated tickets.
 
 If you just want to get started already (and nobody would blame you!), try
-taking a look at the list of `easy tickets that need patches`__ and the
-`easy tickets that have patches which need improvement`__. If you're familiar
+taking a look at the list of `easy tickets without a branch`__ and the
+`easy tickets that have branches which need improvement`__. If you're familiar
 with writing tests, you can also look at the list of
 `easy tickets that need tests`__. Remember to follow the guidelines about
 claiming tickets that were mentioned in the link to Django's documentation on
-:doc:`claiming tickets and submitting patches
+:doc:`claiming tickets and submitting branches
 </internals/contributing/writing-code/submitting-patches>`.
 
 __ https://code.djangoproject.com/query?status=new&status=reopened&has_patch=0&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority
@@ -622,9 +621,9 @@ __ https://code.djangoproject.com/query?status=new&status=reopened&needs_tests=1
 What's next after creating a pull request?
 ------------------------------------------
 
-After a ticket has a patch, it needs to be reviewed by a second set of eyes.
+After a ticket has a branch, it needs to be reviewed by a second set of eyes.
 After submitting a pull request, update the ticket metadata by setting the
 flags on the ticket to say "has patch", "doesn't need tests", etc, so others
-can find it for review. Contributing doesn't necessarily always mean writing a
-patch from scratch. Reviewing existing patches is also a very helpful
+can find it for review. Contributing doesn't necessarily always mean writing
+code from scratch. Reviewing open pull requests is also a very helpful
 contribution. See :doc:`/internals/contributing/triaging-tickets` for details.