mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-22 09:05:43 +00:00
Code Issues 25 Releases Wiki Activity

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

Browse Source
This commit is contained in:
Andreu Vallbona 2024-06-08 12:33:04 +02:00 committed by nessita
parent 3556f63c4c
commit 85240139ca
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.
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

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,
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

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:**
: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
============

85
docs/intro/contributing.txt
View File

@ -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.