docs: Add how-to for Python development (virtualenvs, make test)

source/developers/how-tos/get-ready-for-python-dev.rst

@@ -0,0 +1,82 @@
+How To Get Ready for Python Development
+#######################################
+
+.. How-tos should have a short introduction sentence that captures the user's goal and introduces the steps.
+
+This how-to will help prepare your local system to start developing on a Python-based service that is part of the Open edX Platform.
+
+Assumptions
+***********
+
+.. This section should contain a bulleted list of assumptions you have of the
+   person who is following the How-to.  The assumptions may link to other
+   how-tos if possible.
+
+* You have Git installed
+* You have Python 3.8 installed
+
+Steps
+*****
+
+.. note::
+
+   Some repositories will have a variation of these instructions in their README. Often it will be better to follow the instructions here instead, as the README instructions may be outdated, but keep an eye out for repositories that document special workflows.
+
+First-Time Setup
+================
+
+First, clone the repository with ``git clone <git_url>``. It's best to place all of your Open edX repositories in the same parent directory as each other, as a few of them assume that they will be arranged this way. (If you're not using devstack, this may not matter.)
+
+After navigating to the new directory in your shell, you'll need to set up a virtualenv and install requirements.
+
+A virtualenv contains a copy of your repo's Python dependencies. This avoids dependency version conflicts with your system packages and other repos.
+
+The most basic way of creating a virtualenv is to use the builtin ``venv`` module in Python::
+
+  python3.8 -m venv .venv-3.8
+
+This example creates a virtualenv at ``./.venv-3.8/``. Each time you will be working with Python in the repo, you'll need to activate the virtualenv for that terminal session::
+
+  source .venv-3.8/bin/activate
+
+Once you have done this, any calls to ``python``, ``pip``, or other Python executables will refer to the ones managed by the virtualenv.
+
+.. note::
+
+   If you create virtualenvs inside repos, you'll need to tell git to ignore them. The easiest way to do this is to create a file called ``.gitignore-global`` in your home directory and add the line ``.venv-3.*/``. Alternatively, you can create the virtualenvs elsewhere in your filesystem.
+
+Many developers use wrapper scripts (or write their own using shell aliases). One commonly used tool is ``virtualenvwrapper``, which manages the virtualenv directories outside of repositories; this avoids several issues with git and other tools being able to see the virtualenv, but will require explicitly naming each virtualenv.
+
+Working on a Repo
+=================
+
+#. Make sure you are on the default branch and have the latest version of the code::
+
+     git checkout main
+     git pull
+
+   Some repos instead have ``master`` as their default branch.
+
+#. Activate your virtualenv, as described above.
+#. Install or update the Python requirements for the repo into your virtualenv::
+
+     make requirements
+
+   In a few repos, this might also install NodeJS requirements, or the Makefile target might have a different name.
+
+#. Optionally, ensure you can run tests::
+
+     make test
+
+   Depending on the repository this might run not just unit tests, but also linters and other quality checks. The Makefile may also define a more comprehensive ``test-all`` target.
+
+#. Make a branch for your changes::
+
+     git checkout -b <your_github_username>/<short_descriptive_label>
+
+#. As you change code and add tests, you can use ``make test`` to check if tests are still passing.
+#. Run ``make test`` one more time and commit your changes with ``git commit``. Follow the `conventional commits`_ documentation. Make sure your commit message is informative and describes why the change is being made. While the first line of the message should be terse, the body of the message has plenty of room for details.
+#. Push your changes to GitHub. If you have write access to the repository, you can run ``git push``. If not, you'll need to fork the repository in GitHub. After forking, you can use ``git remote add fork <fork_url>`` to tell git about the fork, and then ``git push fork`` to push your branch to your fork.
+#. In GitHub, open a pull request for your changes and ask for a review.
+
+.. _conventional commits: https://open-edx-proposals.readthedocs.io/en/latest/best-practices/oep-0051-bp-conventional-commits.html