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

Replaced usage of "patch" with more precise terms in contributing docs.

This commit is contained in:
Andreu Vallbona 2024-06-09 16:55:51 +02:00 committed by nessita
parent 82c71f0168
commit 55a2e3136b
3 changed files with 54 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/internals/contributing/localizing.txt
View File

@ -59,13 +59,14 @@ the date, time and numbers formatting particularities of your locale. See
:doc:`/topics/i18n/formatting` for details.
The format files aren't managed by the use of Transifex. To change them, you
must :doc:`create a patch<writing-code/submitting-patches>` against the
Django source tree, as for any code change:
must:
* Create a diff against the current Git main branch.
* :doc:`Create a pull request<writing-code/submitting-patches>` against the
Django Git ``main`` branch, as for any code change.
* Open a ticket in Django's ticket system, set its ``Component`` field to
``Translations``, and attach the patch to it.
``Translations``, set the "has patch" flag, and include the link to the pull
request.
.. _Transifex: https://www.transifex.com/
.. _Django project page: https://app.transifex.com/django/django/

30
docs/internals/contributing/triaging-tickets.txt
View File

@ -35,8 +35,8 @@ Triage workflow
Unfortunately, not all bug reports and feature requests in the ticket tracker
provide all the :doc:`required details<bugs-and-features>`. A number of
tickets have patches, but those patches don't meet all the requirements of a
:ref:`good patch<patch-style>`.
tickets have proposed solutions, but those don't necessarily meet all the
requirements :ref:`adhering to the guidelines for contributing <patch-style>`.
One way to help out is to *triage* tickets that have been created by other
users.
@ -56,7 +56,7 @@ Since a picture is worth a thousand words, let's start there:
We've got two roles in this diagram:
* Mergers: people with commit access who are responsible for making the
final decision to merge a patch.
final decision to merge a change.
* Ticket triagers: anyone in the Django community who chooses to
become involved in Django's development process. Our Trac installation
@ -115,18 +115,18 @@ 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 patch for it. This is generally more
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 patch if you are in doubt.
feedback before writing an extensive contribution if you are in doubt.
* **Accepted + Has Patch**
The ticket is waiting for people to review the supplied patch. This means
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.
@ -143,7 +143,7 @@ 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
commit-ready patch. A :ref:`merger <mergers-team>` now needs to give the patch
commit-ready contribution. A :ref:`merger <mergers-team>` 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
@ -169,9 +169,9 @@ A number of flags, appearing as checkboxes in Trac, can be set on a ticket:
Has patch
---------
This means the ticket has an associated
:doc:`patch<writing-code/submitting-patches>`. These will be reviewed
to see if the patch is "good".
This means the ticket has an associated solution. These will be reviewed to
ensure they adhere to the :doc:`documented guidelines
<writing-code/submitting-patches>`.
The following three fields (Needs documentation, Needs tests,
Patch needs improvement) apply only if a patch has been supplied.
@ -187,12 +187,12 @@ Needs tests
-----------
This flags the patch as needing associated unit tests. Again, this
is a required part of a valid patch.
is a required part of a valid contribution.
Patch needs improvement
-----------------------
This flag means that although the ticket *has* a patch, it's not quite
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.
@ -200,7 +200,7 @@ doesn't meet our standards.
Easy pickings
-------------
Tickets that would require small, easy, patches.
Tickets that would require small, easy, changes.
Type
----
@ -374,7 +374,7 @@ Then, you can help out by:
you should raise it for discussion (referencing the relevant tickets)
on the `Django Forum`_ or |django-developers|.
* Verify if patches submitted by other users are correct. If they are correct
* Verify if solutions submitted by others are correct. If they are correct
and also contain appropriate documentation and tests then move them to the
"Ready for Checkin" stage. If they are not correct then leave a comment to
explain why and set the corresponding flags ("Patch needs improvement",
@ -383,7 +383,7 @@ Then, you can help out by:
.. 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 proposals as
suggested above.
You can also find more :doc:`new-contributors`.

69
docs/internals/contributing/writing-code/submitting-patches.txt
View File

@ -1,10 +1,10 @@
==================
Submitting patches
==================
========================
Submitting contributions
========================
We're always grateful for patches to Django's code. Indeed, bug reports
with associated patches will get fixed *far* more quickly than those
without patches.
We're always grateful for contributions to Django's code. Indeed, bug reports
with associated contributions will get fixed *far* more quickly than those
without a solution.
Typo fixes and trivial documentation changes
============================================
@ -52,7 +52,7 @@ and time availability), claim it by following these steps:
.. note::
The Django software foundation requests that anyone contributing more than
a trivial patch to Django sign and submit a `Contributor License
a trivial change to Django sign and submit a `Contributor License
Agreement`_, this ensures that the Django Software Foundation has clear
license to all contributions allowing for a clear license for all users.
@ -86,35 +86,32 @@ Going through the steps of claiming tickets is overkill in some cases.
In the case of small changes, such as typos in the documentation or small bugs
that will only take a few minutes to fix, you don't need to jump through the
hoops of claiming tickets. Submit your patch directly and you're done!
hoops of claiming tickets. Submit your changes directly and you're done!
It is *always* acceptable, regardless whether someone has claimed it or not, to
submit patches to a ticket if you happen to have a patch ready.
link proposals to a ticket if you happen to have the changes ready.
.. _patch-style:
Patch style
===========
Contribution style
==================
Make sure that any contribution you do fulfills at least the following
requirements:
* The code required to fix a problem or add a feature is an essential part
of a patch, but it is not the only part. A good patch should also include a
of a solution, but it is not the only part. A good fix should also include a
:doc:`regression test <unit-tests>` to validate the behavior that has been
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.
* If the code associated with a patch adds a new feature, or modifies
behavior of an existing feature, the patch should also contain
documentation.
* If the code adds a new feature, or modifies the behavior of an existing
feature, the change should also contain documentation.
When you think your work is ready to be reviewed, send :doc:`a GitHub pull
request <working-with-git>`. Please review the patch yourself using our
:ref:`patch review checklist <patch-review-checklist>` first.
request <working-with-git>`.
If you can't send a pull request for some reason, you can also use patches in
Trac. When using this style, follow these guidelines.
@ -129,7 +126,7 @@ Trac. When using this style, follow these guidelines.
Regardless of the way you submit your work, follow these steps.
* Make sure your code fulfills the requirements in our :ref:`patch review
* Make sure your code fulfills the requirements in our :ref:`contribution
checklist <patch-review-checklist>`.
* Check the "Has patch" box on the ticket and make sure the "Needs
@ -140,17 +137,18 @@ Regardless of the way you submit your work, follow these steps.
.. _ticket tracker: https://code.djangoproject.com/
.. _Development dashboard: https://dashboard.djangoproject.com/
Non-trivial patches
===================
Non-trivial contributions
=========================
A "non-trivial" patch is one that is more than a small bug fix. It's a patch
that introduces Django functionality and makes some sort of design decision.
A "non-trivial" contribution is one that is more than a small bug fix. It's a
change that introduces new Django functionality and makes some sort of design
decision.
If you provide a non-trivial patch, include evidence that alternatives have
If you provide a non-trivial change, include evidence that alternatives have
been discussed on the `Django Forum`_ or |django-developers| list.
If you're not sure whether your patch should be considered non-trivial, ask on
the ticket for opinions.
If you're not sure whether your contribution should be considered non-trivial,
ask on the ticket for opinions.
.. _Django Forum: https://forum.djangoproject.com/
@ -253,15 +251,15 @@ Once you have completed these steps, you are finished with the deprecation.
In each :term:`feature release <Feature release>`, all
``RemovedInDjangoXXWarning``\s matching the new version are removed.
JavaScript patches
==================
JavaScript contributions
========================
For information on JavaScript patches, see the :ref:`javascript-patches`
For information on JavaScript contributions, see the :ref:`javascript-patches`
documentation.
.. _patch-review-checklist:
Patch review checklist
Contribution checklist
======================
Use this checklist to review a pull request. If you are reviewing a pull
@ -271,14 +269,15 @@ If you've left comments for improvement on the pull request, please tick the
appropriate flags on the Trac ticket based on the results of your review:
"Patch needs improvement", "Needs documentation", and/or "Needs tests". As time
and interest permits, mergers do final reviews of "Ready for checkin" tickets
and will either commit the patch or bump it back to "Accepted" if further works
need to be done. If you're looking to become a merger, doing thorough reviews
of patches is a great way to earn trust.
and will either commit the changes or bump it back to "Accepted" if further
work needs to be done. If you're looking to become a merger, 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 <https://dashboard.djangoproject.com/>`_.
Looking to get your patch reviewed? Ensure the Trac flags on the ticket are
set so that the ticket appears in that queue.
Looking to get your pull request reviewed? Ensure the Trac flags on the ticket
are set so that the ticket appears in that queue.
Documentation
-------------