1
0
mirror of https://github.com/django/django.git synced 2024-12-23 01:25:58 +00:00

Fixed #24943 -- Updated contributing tutorial to use virtualenv

This commit is contained in:
Markus Amalthea Magnuson 2015-06-08 23:56:29 +02:00 committed by Tim Graham
parent 65296b3be3
commit fb1ba4d63e
2 changed files with 107 additions and 32 deletions

View File

@ -68,6 +68,17 @@ It contains lots of great information and is a must read for anyone who'd like
to become a regular contributor to Django. If you've got questions, it's to become a regular contributor to Django. If you've got questions, it's
probably got the answers. probably got the answers.
.. admonition:: Python 3 required!
This tutorial assumes you are using Python 3. Get the latest version at
`Python's download page <https://www.python.org/download/>`_ or with your
operating system's package manager.
.. admonition:: For Windows users
When installing Python on Windows, make sure you check the option "Add
python.exe to Path", so that it is always available on the command line.
Code of Conduct Code of Conduct
=============== ===============
@ -82,8 +93,14 @@ development version of Django and to generate patch files for the changes you
make. make.
To check whether or not you have Git installed, enter ``git`` into the command To check whether or not you have Git installed, enter ``git`` into the command
line. If you get messages saying that this command could not be found, you'll have line. If you get messages saying that this command could not be found, you'll
to download and install it, see `Git's download page`__. have to download and install it, see `Git's download page`__.
.. admonition:: For Windows users
When installing Git on Windows, it is recommended that you pick the
"Git Bash" option so that Git runs in its own shell. This tutorial assumes
that's how you have installed it.
If you're not that familiar with Git, you can always find out more about its If you're not that familiar with Git, you can always find out more about its
commands (once it's installed) by typing ``git help`` into the command line. commands (once it's installed) by typing ``git help`` into the command line.
@ -103,26 +120,95 @@ Download the Django source code repository using the following command:
$ git clone https://github.com/django/django.git $ git clone https://github.com/django/django.git
.. note:: Now that you have a local copy of Django, you can install it just like you would
install any package using ``pip``. The most convenient way to do so is by using
a *virtual environment* (or virtualenv) which is a feature built into Python
that allows you to keep a separate directory of installed packages for each of
your projects so that they don't interfere with each other.
For users who wish to use `virtualenv`__, you can use: It's a good idea to keep all your virtualenvs in one place, for example in
``.virtualenvs/`` in your home directory. Create it if it doesn't exist yet:
.. code-block:: console
$ mkdir ~/.virtualenvs
Now create a new virtualenv by running:
.. code-block:: console
$ python3 -m venv ~/.virtualenvs/djangodev
The path is where the new environment will be saved on your computer.
.. admonition:: For Windows users
Using the built-in ``venv`` module will not work if you are also using the
Git Bash shell on Windows, since activation scripts are only created for the
system shell (``.bat``) and PowerShell (``.ps1``). Use the ``virtualenv``
package instead:
.. code-block:: none
$ pip install virtualenv
$ virtualenv ~/.virtualenvs/djangodev
.. admonition:: For Ubuntu users
On some versions of Ubuntu the above command might fail. Use the
``virtualenv`` package instead, first making sure you have ``pip3``:
.. code-block:: console .. code-block:: console
$ pip install -e /path/to/your/local/clone/django/ $ sudo apt-get install python3-pip
$ # Prefix the next command with sudo if it gives a permission denied error
$ pip3 install virtualenv
$ virtualenv --python=`which python3` ~/.virtualenvs/djangodev
(where ``django`` is the directory of your clone that contains The final step in setting up your virtualenv is to activate it:
``setup.py``) to link your cloned checkout into a virtual environment. This
is a great option to isolate your development copy of Django from the rest
of your system and avoids potential package conflicts.
__ http://www.virtualenv.org .. code-block:: console
$ source ~/.virtualenvs/djangodev/bin/activate
If the ``source`` command is not available, you can try using a dot instead:
.. code-block:: console
$ . ~/.virtualenvs/djangodev/bin/activate
.. admonition:: For Windows users
To activate your virtualenv on Windows, run:
.. code-block:: none
$ source ~/virtualenvs/djangodev/Scripts/activate
You have to activate the virtualenv whenever you open a new terminal window.
virtualenvwrapper__ is a useful tool for making this more convenient.
__ https://virtualenvwrapper.readthedocs.org/en/latest/
Anything you install through ``pip`` from now on will be installed in your new
virtualenv, isolated from other environments and system-wide packages. Also, the
name of the currently activated virtualenv is displayed on the command line to
help you keep track of which one you are using. Go ahead and install the
previously cloned copy of Django:
.. code-block:: console
$ pip install -e /path/to/your/local/clone/django/
The installed version of Django is now pointing at your local copy. You will
immediately see any changes you make to it, which is of great help when writing
your first patch.
Rolling back to a previous revision of Django Rolling back to a previous revision of Django
============================================= =============================================
For this tutorial, we'll be using ticket :ticket:`24788` as a case study, so we'll For this tutorial, we'll be using ticket :ticket:`24788` as a case study, so
rewind Django's version history in git to before that ticket's patch was we'll rewind Django's version history in git to before that ticket's patch was
applied. This will allow us to go through all of the steps involved in writing applied. This will allow us to go through all of the steps involved in writing
that patch from scratch, including running Django's test suite. that patch from scratch, including running Django's test suite.
@ -164,26 +250,14 @@ into the Django ``tests/`` directory and then running:
.. code-block:: console .. code-block:: console
$ pip install -r requirements/py3.txt # or py2.txt if you are running Python 2 $ pip install -r requirements/py3.txt
Now we are ready to run the test suite. If you're using GNU/Linux, Mac OS X or Now we are ready to run the test suite. If you're using GNU/Linux, Mac OS X or
some other flavor of Unix, run: some other flavor of Unix, run:
.. code-block:: console .. code-block:: console
$ PYTHONPATH=.. ./runtests.py $ ./runtests.py
If you're on Windows, the above should work provided that you are using
"Git Bash" provided by the default Git install. GitHub has a `nice tutorial`__.
__ https://help.github.com/articles/set-up-git#platform-windows
.. note::
If you're using ``virtualenv``, you can omit ``PYTHONPATH=..`` when running
the tests. This instructs Python to look for Django in the parent directory
of ``tests``. ``virtualenv`` puts your copy of Django on the ``PYTHONPATH``
automatically.
Now sit back and relax. Django's entire test suite has over 9,600 different Now sit back and relax. Django's entire test suite has over 9,600 different
tests, so it can take anywhere from 5 to 15 minutes to run, depending on the tests, so it can take anywhere from 5 to 15 minutes to run, depending on the
@ -311,7 +385,7 @@ into the Django ``tests/`` directory and run:
.. code-block:: console .. code-block:: console
$ PYTHONPATH=.. ./runtests.py forms_tests $ ./runtests.py forms_tests
If the tests ran correctly, you should see one failure corresponding to the test If the tests ran correctly, you should see one failure corresponding to the test
method we added. If all of the tests passed, then you'll want to make sure that method we added. If all of the tests passed, then you'll want to make sure that
@ -332,9 +406,9 @@ right after the ``field_order`` attribute::
class BaseForm(object): class BaseForm(object):
# This is the main implementation of all the Form logic. Note that this # This is the main implementation of all the Form logic. Note that this
# class is different than Form. See the comments by the Form class for more # class is different than Form. See the comments by the Form class for
# information. Any improvements to the form API should be made to *this* # more information. Any improvements to the form API should be made to
# class, not to the Form class. # *this* class, not to the Form class.
field_order = None field_order = None
prefix = None prefix = None
@ -348,7 +422,7 @@ Django ``tests/`` directory and run:
.. code-block:: console .. code-block:: console
$ PYTHONPATH=.. ./runtests.py forms_tests $ ./runtests.py forms_tests
Oops, good thing we wrote those tests! You should still see one failure with Oops, good thing we wrote those tests! You should still see one failure with
the following exception:: the following exception::
@ -380,7 +454,7 @@ directory and run:
.. code-block:: console .. code-block:: console
$ PYTHONPATH=.. ./runtests.py $ ./runtests.py
As long as you don't see any failures, you're good to go. As long as you don't see any failures, you're good to go.

View File

@ -923,6 +923,7 @@ versioning
vertices vertices
viewable viewable
virtualenv virtualenv
virtualenvs
virtualized virtualized
Votizen Votizen
webapps webapps