mirror of
https://github.com/django/django.git
synced 2025-10-24 06:06:09 +00:00
[4.2.x] Refs #34140 -- Applied rst code-block to non-Python examples.
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for
reviews.
Backport of 534ac48297 from main.
This commit is contained in:
committed by
Mariusz Felisiak
parent
4a89aa25c9
commit
b784768eef
@@ -25,7 +25,9 @@ Django's `Git repository`_ is hosted on `GitHub`_, and it is recommended
|
||||
that you also work using GitHub.
|
||||
|
||||
After installing Git, the first thing you should do is set up your name and
|
||||
email::
|
||||
email:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ git config --global user.name "Your Real Name"
|
||||
$ git config --global user.email "you@email.com"
|
||||
@@ -43,25 +45,33 @@ Setting up local repository
|
||||
|
||||
When you have created your GitHub account, with the nick "GitHub_nick", and
|
||||
`forked Django's repository <https://github.com/django/django/fork>`__,
|
||||
create a local copy of your fork::
|
||||
create a local copy of your fork:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git clone https://github.com/GitHub_nick/django.git
|
||||
|
||||
This will create a new directory "django", containing a clone of your GitHub
|
||||
repository. The rest of the git commands on this page need to be run within the
|
||||
cloned directory, so switch to it now::
|
||||
cloned directory, so switch to it now:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
cd django
|
||||
|
||||
Your GitHub repository will be called "origin" in Git.
|
||||
|
||||
You should also set up ``django/django`` as an "upstream" remote (that is, tell
|
||||
git that the reference Django repository was the source of your fork of it)::
|
||||
git that the reference Django repository was the source of your fork of it):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git remote add upstream https://github.com/django/django.git
|
||||
git fetch upstream
|
||||
|
||||
You can add other remotes similarly, for example::
|
||||
You can add other remotes similarly, for example:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git remote add akaariai https://github.com/akaariai/django.git
|
||||
|
||||
@@ -69,19 +79,25 @@ Working on a ticket
|
||||
===================
|
||||
|
||||
When working on a ticket, create a new branch for the work, and base that work
|
||||
on ``upstream/main``::
|
||||
on ``upstream/main``:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git checkout -b ticket_xxxxx upstream/main
|
||||
|
||||
The -b flag creates a new branch for you locally. Don't hesitate to create new
|
||||
branches even for the smallest things - that's what they are there for.
|
||||
|
||||
If instead you were working for a fix on the 1.4 branch, you would do::
|
||||
If instead you were working for a fix on the 1.4 branch, you would do:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x
|
||||
|
||||
Assume the work is carried on the ticket_xxxxx branch. Make some changes and
|
||||
commit them::
|
||||
commit them:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git commit
|
||||
|
||||
@@ -91,14 +107,18 @@ uncomfortable with English, try at least to describe precisely what the commit
|
||||
does.
|
||||
|
||||
If you need to do additional work on your branch, commit as often as
|
||||
necessary::
|
||||
necessary:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git commit -m 'Added two more tests for edge cases'
|
||||
|
||||
Publishing work
|
||||
---------------
|
||||
|
||||
You can publish your work on GitHub by running::
|
||||
You can publish your work on GitHub by running:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git push origin ticket_xxxxx
|
||||
|
||||
@@ -154,7 +174,9 @@ repository. Your commit "Added two more tests" would be unhelpful noise.
|
||||
Instead, we would rather only have one commit containing all your work.
|
||||
|
||||
To rework the history of your branch you can squash the commits into one by
|
||||
using interactive rebase::
|
||||
using interactive rebase:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git rebase -i HEAD~2
|
||||
|
||||
@@ -167,7 +189,9 @@ the editor. A second editor window should open, so you can reword the
|
||||
commit message for the commit now that it includes both your steps.
|
||||
|
||||
You can also use the "edit" option in rebase. This way you can change a single
|
||||
commit, for example to fix a typo in a docstring::
|
||||
commit, for example to fix a typo in a docstring:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git rebase -i HEAD~3
|
||||
# Choose edit, pick, pick for the commits
|
||||
@@ -180,7 +204,9 @@ commit, for example to fix a typo in a docstring::
|
||||
|
||||
If your topic branch is already published at GitHub, for example if you're
|
||||
making minor changes to take into account a review, you will need to force-push
|
||||
the changes::
|
||||
the changes:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git push -f origin ticket_xxxxx
|
||||
|
||||
@@ -193,7 +219,9 @@ After upstream has changed
|
||||
--------------------------
|
||||
|
||||
When upstream (``django/django``) has changed, you should rebase your work. To
|
||||
do this, use::
|
||||
do this, use:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
@@ -225,12 +253,16 @@ easily check what changes you have done.
|
||||
|
||||
In this case, do the changes required by the reviewer. Commit as often as
|
||||
necessary. Before publishing the changes, rebase your work. If you added two
|
||||
commits, you would run::
|
||||
commits, you would run:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git rebase -i HEAD~2
|
||||
|
||||
Squash the second commit into the first. Write a commit message along the lines
|
||||
of::
|
||||
of:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
Made changes asked in review by <reviewer>
|
||||
|
||||
@@ -238,7 +270,9 @@ of::
|
||||
- Reworded the docstring of bar()
|
||||
|
||||
Finally, push your work back to your GitHub repository. Since you didn't touch
|
||||
the public commits during the rebase, you should not need to force-push::
|
||||
the public commits during the rebase, you should not need to force-push:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git push origin ticket_xxxxx
|
||||
|
||||
@@ -252,7 +286,9 @@ Working on a patch
|
||||
|
||||
One of the ways that developers can contribute to Django is by reviewing
|
||||
patches. Those patches will typically exist as pull requests on GitHub and
|
||||
can be easily integrated into your local repository::
|
||||
can be easily integrated into your local repository:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
git checkout -b pull_xxxxx upstream/main
|
||||
curl -L https://github.com/django/django/pull/xxxxx.patch | git am
|
||||
|
||||
Reference in New Issue
Block a user