p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

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

Backport of 85240139ca from main.
This commit is contained in:
Andreu Vallbona 2024-06-08 12:33:04 +02:00 committed by Natalia
parent d14e815568
commit bae675f4a4
4 changed files with 60 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
docs/faq/contributing.txt
View File

@ -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. Thanks for asking! We've written an entire document devoted to this question.
It's titled :doc:`Contributing to Django </internals/contributing/index>`. 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! 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 database, are those instructions clear enough even for someone not
familiar with it? familiar with it?
* If there are several patches attached to the ticket, is it clear what * If there are several branches linked to the ticket, is it clear what each one
each one does, which ones can be ignored and which matter? 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, 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 -- If your contribution is not suitable for inclusion in Django, we won't ignore
we'll just close the ticket. So if your ticket is still open, it doesn't mean 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. 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 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 post your message right before a release deadline, you're not likely to get the
sort of attention you require. 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 additional attention -- certainly not the attention that you need in order to
get your issue addressed. 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 Seriously - we're not ignoring you. If your contribution is not suitable for
inclusion in Django, we'll close the ticket. For all the other tickets, we 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 need to prioritize our efforts, which means that some tickets will be
addressed before others. 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 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 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 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 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 attention. Again, this is a matter of prioritizing scarce resources. By

2
docs/howto/windows.txt
View File

@ -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, 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 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 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 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 versions, the steps would be similar. You will need to be familiar with using

2
docs/index.txt
View File

@ -27,7 +27,7 @@ Are you new to Django or to programming? This is the place to start!
* **Advanced Tutorials:** * **Advanced Tutorials:**
:doc:`How to write reusable apps <intro/reusable-apps>` | :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 Getting help
============ ============

85
docs/intro/contributing.txt
View File

@ -1,6 +1,6 @@
=================================== ==========================================
Writing your first patch for Django Writing your first contribution for Django
=================================== ==========================================
Introduction Introduction
============ ============
@ -52,16 +52,16 @@ __ https://web.libera.chat/#django-dev
What does this tutorial cover? 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 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: tools and the processes involved. Specifically, we'll be covering the following:
* Installing Git. * Installing Git.
* Downloading a copy of Django's development version. * Downloading a copy of Django's development version.
* Running Django's test suite. * Running Django's test suite.
* Writing a test for your patch. * Writing a test for your changes.
* Writing the code for your patch. * Writing the code for your changes.
* Testing your patch. * Testing your changes.
* Submitting a pull request. * Submitting a pull request.
* Where to look for more information. * Where to look for more information.
@ -91,7 +91,7 @@ Installing Git
============== ==============
For this tutorial, you'll need Git installed to download the current 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. make.
To check whether or not you have Git installed, enter ``git`` into the command 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 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 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 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>`, 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 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 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 of great help when writing your first contribution, especially if testing
to the UI. any changes to the UI.
You can follow the :doc:`tutorial</intro/tutorial01>` for help in creating a You can follow the :doc:`tutorial</intro/tutorial01>` for help in creating a
Django project. Django project.
@ -279,8 +279,8 @@ imaginary details:
We'll now implement this feature and associated tests. 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: 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 Writing some tests for your ticket
================================== ==================================
In most cases, for a patch to be accepted into Django it has to include tests. In most cases, for a contribution to be accepted into Django it has to include
For bug fix patches, this means writing a regression test to ensure that the tests. For bug fix contributions, this means writing a regression test to
bug is never reintroduced into Django later on. A regression test should be ensure that the bug is never reintroduced into Django later on. A regression
written in such a way that it will fail while the bug still exists and pass test should be written in such a way that it will fail while the bug still
once the bug has been fixed. For patches containing new features, you'll need exists and pass once the bug has been fixed. For contributions containing new
to include tests which ensure that the new features are working correctly. features, you'll need to include tests which ensure that the new features are
They too should fail when the new feature is not present, and then pass once it working correctly. They too should fail when the new feature is not present,
has been implemented. and then pass once it has been implemented.
A good way to do this is to write your new tests first, before making any 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 changes to the code. This style of development is called
`test-driven development`__ and can be applied to both entire projects and `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 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. 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 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 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 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 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 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 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: changes ready for commit, run:
.. console:: .. console::
@ -528,12 +528,11 @@ Use the arrow keys to move up and down.
+ def test_make_toast(self): + def test_make_toast(self):
+ self.assertEqual(make_toast(), 'toast') + self.assertEqual(make_toast(), 'toast')
When you're done previewing the patch, hit the ``q`` key to return to the When you're done previewing the changes, hit the ``q`` key to return to the
command line. If the patch's content looked okay, it's time to commit the command line. If the diff looked okay, it's time to commit the changes.
changes.
Committing the changes in the patch Committing the changes
=================================== ======================
To commit 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 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): "ticket_99999" with the name of your branch if it's different):
.. console:: .. 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. 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 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 Next steps
========== ==========
@ -578,14 +577,14 @@ codebase.
More information for new contributors 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: information on contributing that you should probably take a look at:
* You should make sure to read Django's documentation on * 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>`. </internals/contributing/writing-code/submitting-patches>`.
It covers Trac etiquette, how to claim tickets for yourself, expected 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 * First time contributors should also read Django's :doc:`documentation
for first time contributors</internals/contributing/new-contributors/>`. for first time contributors</internals/contributing/new-contributors/>`.
It has lots of good advice for those of us who are new to helping out 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 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 tickets with the "easy pickings" criterion. These tickets are often much
simpler in nature and are great for first time contributors. Once you're 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 familiar with contributing to Django, you can start working on more difficult
more difficult and complicated tickets. and complicated tickets.
If you just want to get started already (and nobody would blame you!), try 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 taking a look at the list of `easy tickets without a branch`__ and the
`easy tickets that have patches which need improvement`__. If you're familiar `easy tickets that have branches which need improvement`__. If you're familiar
with writing tests, you can also look at the list of with writing tests, you can also look at the list of
`easy tickets that need tests`__. Remember to follow the guidelines about `easy tickets that need tests`__. Remember to follow the guidelines about
claiming tickets that were mentioned in the link to Django's documentation on 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>`. </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 __ 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? 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 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 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 can find it for review. Contributing doesn't necessarily always mean writing
patch from scratch. Reviewing existing patches is also a very helpful code from scratch. Reviewing open pull requests is also a very helpful
contribution. See :doc:`/internals/contributing/triaging-tickets` for details. contribution. See :doc:`/internals/contributing/triaging-tickets` for details.