mirror of https://github.com/django/django.git
[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
Natalia
parent
d14e815568
commit
bae675f4a4
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
============
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue