mirror of https://github.com/django/django.git
Refs #31676 -- Used term "merger" instead of "committer" in docs.
Follow up to caa2dd08c4
.
Co-authored-by: Carlton Gibson <carlton.gibson@noumenal.es>
This commit is contained in:
parent
7325d29152
commit
653daaa60c
Binary file not shown.
Binary file not shown.
File diff suppressed because one or more lines are too long
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 20 KiB |
|
@ -2,7 +2,7 @@
|
||||||
Committing code
|
Committing code
|
||||||
===============
|
===============
|
||||||
|
|
||||||
This section is addressed to the committers and to anyone interested in knowing
|
This section is addressed to the mergers and to anyone interested in knowing
|
||||||
how code gets committed into Django. If you're a community member who wants to
|
how code gets committed into Django. If you're a community member who wants to
|
||||||
contribute code to Django, look at :doc:`writing-code/working-with-git` instead.
|
contribute code to Django, look at :doc:`writing-code/working-with-git` instead.
|
||||||
|
|
||||||
|
@ -16,9 +16,9 @@ requests.
|
||||||
|
|
||||||
When committing a pull request, make sure each individual commit matches the
|
When committing a pull request, make sure each individual commit matches the
|
||||||
commit guidelines described below. Contributors are expected to provide the
|
commit guidelines described below. Contributors are expected to provide the
|
||||||
best pull requests possible. In practice however, committers - who will likely
|
best pull requests possible. In practice however, mergers - who will likely be
|
||||||
be more familiar with the commit guidelines - may decide to bring a commit up
|
more familiar with the commit guidelines - may decide to bring a commit up to
|
||||||
to standard themselves.
|
standard themselves.
|
||||||
|
|
||||||
You may want to have Jenkins or GitHub actions test the pull request with one
|
You may want to have Jenkins or GitHub actions test the pull request with one
|
||||||
of the pull request builders that doesn't run automatically, such as Oracle or
|
of the pull request builders that doesn't run automatically, such as Oracle or
|
||||||
|
@ -90,7 +90,7 @@ Django's commit history as usable as possible:
|
||||||
* Trivial and small patches usually are best done in one commit. Medium to
|
* Trivial and small patches usually are best done in one commit. Medium to
|
||||||
large work may be split into multiple commits if it makes sense.
|
large work may be split into multiple commits if it makes sense.
|
||||||
|
|
||||||
Practicality beats purity, so it is up to each committer to decide how much
|
Practicality beats purity, so it is up to each merger to decide how much
|
||||||
history mangling to do for a pull request. The main points are engaging the
|
history mangling to do for a pull request. The main points are engaging the
|
||||||
community, getting work done, and having a usable commit history.
|
community, getting work done, and having a usable commit history.
|
||||||
|
|
||||||
|
@ -192,8 +192,8 @@ Django's Git repository:
|
||||||
Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
|
Backport of 80c0cbf1c97047daed2c5b41b296bbc56fe1d7e3 from main.
|
||||||
|
|
||||||
There's a `script on the wiki
|
There's a `script on the wiki
|
||||||
<https://code.djangoproject.com/wiki/CommitterTips#AutomatingBackports>`_
|
<https://code.djangoproject.com/wiki/MergerTips#AutomatingBackports>`_ to
|
||||||
to automate this.
|
automate this.
|
||||||
|
|
||||||
If the commit fixes a regression, include this in the commit message:
|
If the commit fixes a regression, include this in the commit message:
|
||||||
|
|
||||||
|
@ -211,7 +211,7 @@ Nobody's perfect; mistakes will be committed.
|
||||||
But try very hard to ensure that mistakes don't happen. Just because we have a
|
But try very hard to ensure that mistakes don't happen. Just because we have a
|
||||||
reversion policy doesn't relax your responsibility to aim for the highest
|
reversion policy doesn't relax your responsibility to aim for the highest
|
||||||
quality possible. Really: double-check your work, or have it checked by
|
quality possible. Really: double-check your work, or have it checked by
|
||||||
another committer, **before** you commit it in the first place!
|
another merger, **before** you commit it in the first place!
|
||||||
|
|
||||||
When a mistaken commit is discovered, please follow these guidelines:
|
When a mistaken commit is discovered, please follow these guidelines:
|
||||||
|
|
||||||
|
@ -231,10 +231,9 @@ When a mistaken commit is discovered, please follow these guidelines:
|
||||||
* If the problem is small (a feature commit after feature freeze,
|
* If the problem is small (a feature commit after feature freeze,
|
||||||
say), wait it out.
|
say), wait it out.
|
||||||
|
|
||||||
* If there's a disagreement between the committer and the
|
* If there's a disagreement between the merger and the reverter-to-be then try
|
||||||
reverter-to-be then try to work it out on the |django-developers|
|
to work it out on the |django-developers| mailing list. If an agreement can't
|
||||||
mailing list. If an agreement can't be reached then it should
|
be reached then it should be put to a vote.
|
||||||
be put to a vote.
|
|
||||||
|
|
||||||
* If the commit introduced a confirmed, disclosed security
|
* If the commit introduced a confirmed, disclosed security
|
||||||
vulnerability then the commit may be reverted immediately without
|
vulnerability then the commit may be reverted immediately without
|
||||||
|
|
|
@ -55,7 +55,7 @@ Since a picture is worth a thousand words, let's start there:
|
||||||
|
|
||||||
We've got two roles in this diagram:
|
We've got two roles in this diagram:
|
||||||
|
|
||||||
* Committers: people with commit access who are responsible for making the
|
* Mergers: people with commit access who are responsible for making the
|
||||||
final decision to merge a patch.
|
final decision to merge a patch.
|
||||||
|
|
||||||
* Ticket triagers: anyone in the Django community who chooses to
|
* Ticket triagers: anyone in the Django community who chooses to
|
||||||
|
@ -84,7 +84,8 @@ By way of example, here we see the lifecycle of an average ticket:
|
||||||
|
|
||||||
* Daisy reviews the pull request and marks the ticket as "Ready for checkin".
|
* Daisy reviews the pull request and marks the ticket as "Ready for checkin".
|
||||||
|
|
||||||
* Jacob, a committer, reviews the pull request and merges it.
|
* Jacob, a :ref:`merger <mergers-team>`, reviews the pull request and merges
|
||||||
|
it.
|
||||||
|
|
||||||
Some tickets require much less feedback than this, but then again some tickets
|
Some tickets require much less feedback than this, but then again some tickets
|
||||||
require much much more.
|
require much much more.
|
||||||
|
@ -142,8 +143,8 @@ Ready For Checkin
|
||||||
|
|
||||||
The ticket was reviewed by any member of the community other than the person
|
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
|
who supplied the patch and found to meet all the requirements for a
|
||||||
commit-ready patch. A committer now needs to give the patch a final
|
commit-ready patch. A :ref:`merger <mergers-team>` now needs to give the patch
|
||||||
review prior to being committed.
|
a final review prior to being committed.
|
||||||
|
|
||||||
There are a lot of pull requests. It can take a while for your patch to get
|
There are a lot of pull requests. It can take a while for your patch to get
|
||||||
reviewed. See the :ref:`contributing code FAQ<new-contributors-faq>` for some
|
reviewed. See the :ref:`contributing code FAQ<new-contributors-faq>` for some
|
||||||
|
|
|
@ -242,10 +242,10 @@ the "Triage Stage" on the corresponding Trac ticket to "Ready for checkin".
|
||||||
If you've left comments for improvement on the pull request, please tick the
|
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:
|
appropriate flags on the Trac ticket based on the results of your review:
|
||||||
"Patch needs improvement", "Needs documentation", and/or "Needs tests". As time
|
"Patch needs improvement", "Needs documentation", and/or "Needs tests". As time
|
||||||
and interest permits, committers do final reviews of "Ready for checkin"
|
and interest permits, mergers do final reviews of "Ready for checkin" tickets
|
||||||
tickets and will either commit the patch or bump it back to "Accepted" if
|
and will either commit the patch or bump it back to "Accepted" if further works
|
||||||
further works need to be done. If you're looking to become a committer,
|
need to be done. If you're looking to become a merger, doing thorough reviews
|
||||||
doing thorough reviews of patches is a great way to earn trust.
|
of patches is a great way to earn trust.
|
||||||
|
|
||||||
Looking for a patch to review? Check out the "Patches needing review" section
|
Looking for a patch to review? Check out the "Patches needing review" section
|
||||||
of the `Django Development Dashboard <https://dashboard.djangoproject.com/>`_.
|
of the `Django Development Dashboard <https://dashboard.djangoproject.com/>`_.
|
||||||
|
|
|
@ -3,8 +3,8 @@ Working with Git and GitHub
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
This section explains how the community can contribute code to Django via pull
|
This section explains how the community can contribute code to Django via pull
|
||||||
requests. If you're interested in how committers handle them, see
|
requests. If you're interested in how :ref:`mergers <mergers-team>` handle
|
||||||
:doc:`../committing-code`.
|
them, see :doc:`../committing-code`.
|
||||||
|
|
||||||
Below, we are going to show how to create a GitHub pull request containing the
|
Below, we are going to show how to create a GitHub pull request containing the
|
||||||
changes for Trac ticket #xxxxx. By creating a fully-ready pull request, you
|
changes for Trac ticket #xxxxx. By creating a fully-ready pull request, you
|
||||||
|
@ -86,9 +86,9 @@ commit them::
|
||||||
git commit
|
git commit
|
||||||
|
|
||||||
When writing the commit message, follow the :ref:`commit message
|
When writing the commit message, follow the :ref:`commit message
|
||||||
guidelines <committing-guidelines>` to ease the work of the committer. If
|
guidelines <committing-guidelines>` to ease the work of the merger. If you're
|
||||||
you're uncomfortable with English, try at least to describe precisely what the
|
uncomfortable with English, try at least to describe precisely what the commit
|
||||||
commit does.
|
does.
|
||||||
|
|
||||||
If you need to do additional work on your branch, commit as often as
|
If you need to do additional work on your branch, commit as often as
|
||||||
necessary::
|
necessary::
|
||||||
|
@ -138,11 +138,10 @@ related Trac ticket explaining what you've done. In particular, you should note
|
||||||
the environment in which you ran the tests, for instance: "all tests pass
|
the environment in which you ran the tests, for instance: "all tests pass
|
||||||
under SQLite and MySQL".
|
under SQLite and MySQL".
|
||||||
|
|
||||||
Pull requests at GitHub have only two states: open and closed. The committer
|
Pull requests at GitHub have only two states: open and closed. The merger who
|
||||||
who will deal with your pull request has only two options: merge it or close
|
will deal with your pull request has only two options: merge it or close it.
|
||||||
it. For this reason, it isn't useful to make a pull request until the code is
|
For this reason, it isn't useful to make a pull request until the code is ready
|
||||||
ready for merging -- or sufficiently close that a committer will finish it
|
for merging -- or sufficiently close that a merger will finish it themselves.
|
||||||
themselves.
|
|
||||||
|
|
||||||
Rebasing branches
|
Rebasing branches
|
||||||
-----------------
|
-----------------
|
||||||
|
@ -245,7 +244,7 @@ the public commits during the rebase, you should not need to force-push::
|
||||||
|
|
||||||
Your pull request should now contain the new commit too.
|
Your pull request should now contain the new commit too.
|
||||||
|
|
||||||
Note that the committer is likely to squash the review commit into the previous
|
Note that the merger is likely to squash the review commit into the previous
|
||||||
commit when committing the code.
|
commit when committing the code.
|
||||||
|
|
||||||
Working on a patch
|
Working on a patch
|
||||||
|
@ -263,7 +262,7 @@ to it. At this point you can run the tests or do anything else you need to
|
||||||
do to investigate the quality of the patch.
|
do to investigate the quality of the patch.
|
||||||
|
|
||||||
For more detail on working with pull requests see the
|
For more detail on working with pull requests see the
|
||||||
:ref:`guidelines for committers <handling-pull-requests>`.
|
:ref:`guidelines for mergers <handling-pull-requests>`.
|
||||||
|
|
||||||
Summary
|
Summary
|
||||||
=======
|
=======
|
||||||
|
|
|
@ -31,8 +31,8 @@ Django from the source code repository
|
||||||
(see :ref:`installing-development-version`). The development version has the
|
(see :ref:`installing-development-version`). The development version has the
|
||||||
latest-and-greatest documentation, just as it has latest-and-greatest code.
|
latest-and-greatest documentation, just as it has latest-and-greatest code.
|
||||||
We also backport documentation fixes and improvements, at the discretion of the
|
We also backport documentation fixes and improvements, at the discretion of the
|
||||||
committer, to the last release branch. That's because it's highly advantageous
|
merger, to the last release branch. That's because it's highly advantageous to
|
||||||
to have the docs for the last release be up-to-date and correct (see
|
have the docs for the last release be up-to-date and correct (see
|
||||||
:ref:`differences-between-doc-versions`).
|
:ref:`differences-between-doc-versions`).
|
||||||
|
|
||||||
Getting started with Sphinx
|
Getting started with Sphinx
|
||||||
|
|
|
@ -100,8 +100,8 @@ any time leading up to the actual release:
|
||||||
#. As the release approaches, watch Trac to make sure no release blockers
|
#. As the release approaches, watch Trac to make sure no release blockers
|
||||||
are left for the upcoming release.
|
are left for the upcoming release.
|
||||||
|
|
||||||
#. Check with the other committers to make sure they don't have any
|
#. Check with the other mergers to make sure they don't have any uncommitted
|
||||||
uncommitted changes for the release.
|
changes for the release.
|
||||||
|
|
||||||
#. Proofread the release notes, including looking at the online version to
|
#. Proofread the release notes, including looking at the online version to
|
||||||
:ref:`catch any broken links <documentation-link-check>` or reST errors, and
|
:ref:`catch any broken links <documentation-link-check>` or reST errors, and
|
||||||
|
|
|
@ -226,9 +226,9 @@ The release candidate marks the string freeze, and it happens at least two
|
||||||
weeks before the final release. After this point, new translatable strings
|
weeks before the final release. After this point, new translatable strings
|
||||||
must not be added.
|
must not be added.
|
||||||
|
|
||||||
During this phase, committers will be more and more conservative with
|
During this phase, mergers will be more and more conservative with backports,
|
||||||
backports, to avoid introducing regressions. After the release candidate, only
|
to avoid introducing regressions. After the release candidate, only release
|
||||||
release blockers and documentation fixes should be backported.
|
blockers and documentation fixes should be backported.
|
||||||
|
|
||||||
In parallel to this phase, ``main`` can receive new features, to be released
|
In parallel to this phase, ``main`` can receive new features, to be released
|
||||||
in the ``A.B+1`` cycle.
|
in the ``A.B+1`` cycle.
|
||||||
|
|
|
@ -211,9 +211,9 @@ We follow this policy:
|
||||||
been released yet, or "New in version X.Y" for released versions.
|
been released yet, or "New in version X.Y" for released versions.
|
||||||
|
|
||||||
* Documentation fixes and improvements may be backported to the last release
|
* Documentation fixes and improvements may be backported to the last release
|
||||||
branch, at the discretion of the committer, however, once a version of
|
branch, at the discretion of the merger, however, once a version of Django is
|
||||||
Django is :ref:`no longer supported<supported-versions-policy>`, that version
|
:ref:`no longer supported<supported-versions-policy>`, that version of the
|
||||||
of the docs won't get any further updates.
|
docs won't get any further updates.
|
||||||
|
|
||||||
* The `main documentation web page`_ includes links to documentation for
|
* The `main documentation web page`_ includes links to documentation for
|
||||||
previous versions. Be sure you are using the version of the docs
|
previous versions. Be sure you are using the version of the docs
|
||||||
|
|
Loading…
Reference in New Issue