Fixed #24943 -- Updated contributing tutorial to use virtualenv

to become a regular contributor to Django. If you've got questions, it's

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

===============

make.

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

to download and install it, see `Git's download page`__.

line. If you get messages saying that this command could not be found, you'll

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

commands (once it's installed) by typing ``git help`` into the command line.

    $ 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

        $ pip install -e /path/to/your/local/clone/django/

    $ mkdir ~/.virtualenvs

Now create a new virtualenv by running:

.. code-block:: console

    $ python3 -m venv ~/.virtualenvs/djangodev

    (where ``django`` is the directory of your clone that contains

    ``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.

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

        $ 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

The final step in setting up your virtualenv is to activate it:

.. code-block:: console

__ http://www.virtualenv.org

    $ 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

=============================================

For this tutorial, we'll be using ticket :ticket:`24788` as a case study, so we'll

rewind Django's version history in git to before that ticket's patch was

For this tutorial, we'll be using ticket :ticket:`24788` as a case study, so

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

that patch from scratch, including running Django's test suite.

.. 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

some other flavor of Unix, run:

.. code-block:: console

    $ PYTHONPATH=.. ./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.

    $ ./runtests.py

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

.. 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

method we added. If all of the tests passed, then you'll want to make sure that

    class BaseForm(object):

        # 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

        # information. Any improvements to the form API should be made to *this*

        # class, not to the Form class.

        # class is different than Form. See the comments by the Form class for

        # more information. Any improvements to the form API should be made to

        # *this* class, not to the Form class.

        field_order = None

        prefix = None

.. 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

the following exception::

.. code-block:: console

    $ PYTHONPATH=.. ./runtests.py

    $ ./runtests.py

As long as you don't see any failures, you're good to go.

vertices

viewable

virtualenv

virtualenvs

virtualized

Votizen

webapps