Fixed #24943 -- Updated contributing tutorial to use virtualenv

docs/intro/contributing.txt

@@ -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
 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
 ===============
 
@@ -82,8 +93,14 @@ development version of Django and to generate patch files for the changes you
 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.
@@ -103,26 +120,95 @@ Download the Django source code repository using the following command:
 
     $ 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
 
-        $ 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
-    ``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 final step in setting up your virtualenv is to activate it:
 
-__ 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
 =============================================
 
-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.
 
@@ -164,26 +250,14 @@ into the Django ``tests/`` directory and then running:
 
 .. 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
@@ -311,7 +385,7 @@ into the Django ``tests/`` directory and run:
 
 .. 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
@@ -332,9 +406,9 @@ right after the ``field_order`` attribute::
 
     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
 
@@ -348,7 +422,7 @@ Django ``tests/`` directory and run:
 
 .. 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::
@@ -380,7 +454,7 @@ directory and run:
 
 .. code-block:: console
 
-    $ PYTHONPATH=.. ./runtests.py
+    $ ./runtests.py
 
 As long as you don't see any failures, you're good to go.
 

docs/spelling_wordlist

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