diff options
| author | Carlton Gibson <carlton.gibson@noumenal.es> | 2023-02-09 16:48:46 +0100 |
|---|---|---|
| committer | Mariusz Felisiak <felisiak.mariusz@gmail.com> | 2023-02-10 21:12:06 +0100 |
| commit | b784768eef75afb32f6d2ce7166551a528bce0ec (patch) | |
| tree | a375a57a50f1766538ea8a62ec49bda352d7f2b9 /docs/internals/contributing/writing-code/working-with-git.txt | |
| parent | 4a89aa25c91e520c247aee428782274dcf10ffd0 (diff) | |
[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 534ac4829764f317cf2fbc4a18354fcc998c1425 from main.
Diffstat (limited to 'docs/internals/contributing/writing-code/working-with-git.txt')
| -rw-r--r-- | docs/internals/contributing/writing-code/working-with-git.txt | 72 |
1 files changed, 54 insertions, 18 deletions
diff --git a/docs/internals/contributing/writing-code/working-with-git.txt b/docs/internals/contributing/writing-code/working-with-git.txt index e1e9d2fa7c..579543f876 100644 --- a/docs/internals/contributing/writing-code/working-with-git.txt +++ b/docs/internals/contributing/writing-code/working-with-git.txt @@ -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 |
