From b784768eef75afb32f6d2ce7166551a528bce0ec Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Thu, 9 Feb 2023 16:48:46 +0100 Subject: [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. --- docs/internals/contributing/committing-code.txt | 6 +- docs/internals/contributing/triaging-tickets.txt | 18 ++++-- .../contributing/writing-code/unit-tests.txt | 10 +-- .../contributing/writing-code/working-with-git.txt | 72 ++++++++++++++++------ .../contributing/writing-documentation.txt | 56 ++++++++++++----- docs/internals/howto-release-django.txt | 58 ++++++++++++----- 6 files changed, 160 insertions(+), 60 deletions(-) (limited to 'docs/internals') diff --git a/docs/internals/contributing/committing-code.txt b/docs/internals/contributing/committing-code.txt index 094c05a6bd..f5be86238e 100644 --- a/docs/internals/contributing/committing-code.txt +++ b/docs/internals/contributing/committing-code.txt @@ -16,7 +16,7 @@ requests. When committing a pull request, make sure each individual commit matches the commit guidelines described below. Contributors are expected to provide the -best pull requests possible. In practice mergers - who will likely be more +best pull requests possible. In practice mergers - who will likely be more familiar with the commit guidelines - may decide to bring a commit up to standard themselves. @@ -27,7 +27,9 @@ Selenium. See the `CI wiki page`_ for instructions. .. _CI wiki page: https://code.djangoproject.com/wiki/CI If you find yourself checking out pull requests locally more often, this git -alias will be helpful:: +alias will be helpful: + +.. code-block:: ini [alias] pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git checkout pr/${1}\" diff --git a/docs/internals/contributing/triaging-tickets.txt b/docs/internals/contributing/triaging-tickets.txt index ce60b8ac4e..c660c34e91 100644 --- a/docs/internals/contributing/triaging-tickets.txt +++ b/docs/internals/contributing/triaging-tickets.txt @@ -413,8 +413,6 @@ the ticket database: Bisecting a regression ====================== -.. highlight:: console - A regression is a bug that's present in some newer version of Django but not in an older one. An extremely helpful piece of information is the commit that introduced the regression. Knowing the commit that caused the change in @@ -425,11 +423,15 @@ Begin by writing a regression test for Django's test suite for the issue. For example, we'll pretend we're debugging a regression in migrations. After you've written the test and confirmed that it fails on the latest main branch, put it in a separate file that you can run standalone. For our example, we'll pretend -we created ``tests/migrations/test_regression.py``, which can be run with:: +we created ``tests/migrations/test_regression.py``, which can be run with: + +.. code-block:: shell $ ./runtests.py migrations.test_regression -Next, we mark the current point in history as being "bad" since the test fails:: +Next, we mark the current point in history as being "bad" since the test fails: + +.. code-block:: shell $ git bisect bad You need to start by "git bisect start" @@ -440,14 +442,18 @@ introduced (i.e. a point where the test passes). Use something like ``git checkout HEAD~100`` to check out an earlier revision (100 commits earlier, in this case). Check if the test fails. If so, mark that point as "bad" (``git bisect bad``), then check out an earlier revision and recheck. Once you -find a revision where your test passes, mark it as "good":: +find a revision where your test passes, mark it as "good": + +.. code-block:: shell $ git bisect good Bisecting: X revisions left to test after this (roughly Y steps) ... Now we're ready for the fun part: using ``git bisect run`` to automate the rest -of the process:: +of the process: + +.. code-block:: shell $ git bisect run tests/runtests.py migrations.test_regression diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt index ba7209991c..0d711a8af1 100644 --- a/docs/internals/contributing/writing-code/unit-tests.txt +++ b/docs/internals/contributing/writing-code/unit-tests.txt @@ -396,13 +396,17 @@ Ensure you have the latest point release of a :ref:`supported Python version that may cause the test suite to fail or hang. On **macOS** (High Sierra and newer versions), you might see this message -logged, after which the tests hang:: +logged, after which the tests hang: + +.. code-block:: pytb objc[42074]: +[__NSPlaceholderDate initialize] may have been in progress in another thread when fork() was called. To avoid this set a ``OBJC_DISABLE_INITIALIZE_FORK_SAFETY`` environment -variable, for example:: +variable, for example: + +.. code-block:: shell $ OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES ./runtests.py @@ -515,8 +519,6 @@ this purpose. Tips for writing tests ====================== -.. highlight:: python - Isolating model registration ---------------------------- 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 `__, -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 @@ -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 diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 4326731796..a89ea050d5 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -192,11 +192,15 @@ documentation: good reason. * The main thing to keep in mind as you write and edit docs is that the - more semantic markup you can add the better. So:: + more semantic markup you can add the better. So: + + .. code-block:: rst Add ``django.contrib.auth`` to your ``INSTALLED_APPS``... - Isn't nearly as helpful as:: + Isn't nearly as helpful as: + + .. code-block:: rst Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`... @@ -219,7 +223,9 @@ documentation: * To improve readability, use ``.. admonition:: Descriptive title`` rather than ``.. note::``. Use these boxes sparingly. -* Use these heading styles:: +* Use these heading styles: + + .. code-block:: rst === One @@ -258,44 +264,58 @@ Django-specific markup Besides :ref:`Sphinx's built-in markup `, Django's docs define some extra description units: -* Settings:: +* Settings: + + .. code-block:: rst .. setting:: INSTALLED_APPS To link to a setting, use ``:setting:`INSTALLED_APPS```. -* Template tags:: +* Template tags: + + .. code-block:: rst .. templatetag:: regroup To link, use ``:ttag:`regroup```. -* Template filters:: +* Template filters: + + .. code-block:: rst .. templatefilter:: linebreaksbr To link, use ``:tfilter:`linebreaksbr```. -* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``):: +* Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``): + + .. code-block:: rst .. fieldlookup:: exact To link, use ``:lookup:`exact```. -* ``django-admin`` commands:: +* ``django-admin`` commands: + + .. code-block:: rst .. django-admin:: migrate To link, use ``:djadmin:`migrate```. -* ``django-admin`` command-line options:: +* ``django-admin`` command-line options: + + .. code-block:: rst .. django-admin-option:: --traceback To link, use ``:option:`command_name --traceback``` (or omit ``command_name`` for the options shared by all commands like ``--verbosity``). -* Links to Trac tickets (typically reserved for patch release notes):: +* Links to Trac tickets (typically reserved for patch release notes): + + .. code-block:: rst :ticket:`12345` @@ -304,7 +324,9 @@ command-line examples involving ``django-admin``, ``manage.py``, ``python``, etc.). In the HTML documentation, it renders a two-tab UI, with one tab showing a Unix-style command prompt and a second tab showing a Windows prompt. -For example, you can replace this fragment:: +For example, you can replace this fragment: + +.. code-block:: rst use this command: @@ -312,7 +334,9 @@ For example, you can replace this fragment:: $ python manage.py shell -with this one:: +with this one: + +.. code-block:: rst use this command: @@ -368,7 +392,9 @@ In other words, since we only keep these annotations around for two releases, it's nice to be able to remove the annotation and its contents without having to reflow, reindent, or edit the surrounding text. For example, instead of putting the entire description of a new or changed feature in a block, do -something like this:: +something like this: + +.. code-block:: rst .. class:: Author(first_name, last_name, middle_name=None) @@ -392,7 +418,9 @@ redundant to do so as these annotations render as "New in Django A.B:" and "Changed in Django A.B", respectively. If a function, attribute, etc. is added, it's also okay to use a -``versionadded`` annotation like this:: +``versionadded`` annotation like this: + +.. code-block:: rst .. attribute:: Author.middle_name diff --git a/docs/internals/howto-release-django.txt b/docs/internals/howto-release-django.txt index 45994af420..75e1f372d4 100644 --- a/docs/internals/howto-release-django.txt +++ b/docs/internals/howto-release-django.txt @@ -2,8 +2,6 @@ How is Django Formed? ===================== -.. highlight:: console - This document explains how to release Django. **Please, keep these instructions up-to-date if you make changes!** The point @@ -56,7 +54,9 @@ You'll need a few things before getting started: ``you@example.com`` is the email address associated with the key you want to use. -* An install of some required Python packages:: +* An install of some required Python packages: + + .. code-block:: shell $ python -m pip install wheel twine @@ -117,7 +117,9 @@ any time leading up to the actual release: #. If this is a feature release, ensure translations from Transifex have been integrated. This is typically done by a separate translation's manager rather than the releaser, but here are the steps. Provided you have an - account on Transifex:: + account on Transifex: + + .. code-block:: shell $ python scripts/manage_translations.py fetch @@ -125,7 +127,9 @@ any time leading up to the actual release: Sometimes there are validation errors which need to be debugged, so avoid doing this task immediately before a release is needed. -#. :ref:`Update the django-admin manual page `:: +#. :ref:`Update the django-admin manual page `: + + .. code-block:: shell $ cd docs $ make man @@ -135,7 +139,9 @@ any time leading up to the actual release: and then commit the changed man page. #. If this is the alpha release of a new series, create a new stable branch - from main. For example, when releasing Django 3.1:: + from main. For example, when releasing Django 3.1: + + .. code-block:: shell $ git checkout -b stable/3.1.x origin/main $ git push origin -u stable/3.1.x:stable/3.1.x @@ -148,7 +154,9 @@ any time leading up to the actual release: #. If this is the "dot zero" release of a new series, create a new branch from the current stable branch in the `django-docs-translations `_ repository. For - example, when releasing Django 2.2:: + example, when releasing Django 2.2: + + .. code-block:: shell $ git checkout -b stable/2.2.x origin/stable/2.1.x $ git push origin stable/2.2.x:stable/2.2.x @@ -176,7 +184,9 @@ OK, this is the fun part, where we actually push out a release! __ https://djangoci.com #. A release always begins from a release branch, so you should make sure - you're on a stable branch and up-to-date. For example:: + you're on a stable branch and up-to-date. For example: + + .. code-block:: shell $ git checkout stable/1.5.x $ git pull @@ -184,7 +194,9 @@ OK, this is the fun part, where we actually push out a release! #. If this is a security release, merge the appropriate patches from ``django-security``. Rebase these patches as necessary to make each one a plain commit on the release branch rather than a merge commit. To ensure - this, merge them with the ``--ff-only`` flag; for example:: + this, merge them with the ``--ff-only`` flag; for example: + + .. code-block:: shell $ git checkout stable/1.5.x $ git merge --ff-only security/1.5.x @@ -214,7 +226,9 @@ OK, this is the fun part, where we actually push out a release! classifier in ``setup.cfg`` to reflect this. Otherwise, make sure the classifier is set to ``Development Status :: 5 - Production/Stable``. -#. Tag the release using ``git tag``. For example:: +#. Tag the release using ``git tag``. For example: + + .. code-block:: shell $ git tag --sign --message="Tag 1.5.1" 1.5.1 @@ -227,7 +241,9 @@ OK, this is the fun part, where we actually push out a release! #. Run ``make -f extras/Makefile`` to generate the release packages. This will create the release packages in a ``dist/`` directory. -#. Generate the hashes of the release packages:: +#. Generate the hashes of the release packages: + + .. code-block:: shell $ cd dist $ md5sum * @@ -303,19 +319,25 @@ Making the release(s) available to the public Now you're ready to actually put the release out there. To do this: #. Upload the release package(s) to the djangoproject server, replacing - A.B. with the appropriate version number, e.g. 1.5 for a 1.5.x release:: + A.B. with the appropriate version number, e.g. 1.5 for a 1.5.x release: + + .. code-block:: shell $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B If this is the alpha release of a new series, you will need to create the directory A.B. -#. Upload the checksum file(s):: +#. Upload the checksum file(s): + + .. code-block:: shell $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt #. Test that the release packages install correctly using ``pip``. Here's one - method:: + method: + + .. code-block:: shell $ RELEASE_VERSION='1.7.2' $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3` @@ -340,7 +362,9 @@ Now you're ready to actually put the release out there. To do this: files). #. Upload the release packages to PyPI (for pre-releases, only upload the wheel - file):: + file): + + .. code-block:: shell $ twine upload -s dist/* @@ -368,7 +392,9 @@ Now you're ready to actually put the release out there. To do this: for the previous release. Update djangoproject.com's `robots.docs.txt`__ file by copying entries from ``manage_translations.py robots_txt`` from the current stable branch in the ``django-docs-translations`` repository. For - example, when releasing Django 2.2:: + example, when releasing Django 2.2: + + .. code-block:: shell $ git checkout stable/2.2.x $ git pull -- cgit v1.3