mirror of
https://github.com/django/django.git
synced 2025-08-04 10:59:45 +00:00
Refs #34140 -- Applied rst code-block to non-Python examples.
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for reviews.
This commit is contained in:
Carlton Gibson
Mariusz Felisiak
parent
7bb741d787
commit
534ac48297
120 changed files with 3998 additions and 1398 deletions
|
|
@ -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}\"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
----------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <sphinx:rst-index>`, 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <django-admin-manpage>`::
|
||||
#. :ref:`Update the django-admin manual page <django-admin-manpage>`:
|
||||
|
||||
.. 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
|
||||
<https://github.com/django/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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue