From 9c3518a7e2ce7a3383e191e035414f2d3adfd8f9 Mon Sep 17 00:00:00 2001
From: jugglinmike <mike@mikepennisi.com>
Date: Tue, 4 Sep 2018 10:56:51 -0400
Subject: [PATCH] Improve documentation for Python usage (#1703)
Update the recommended invocation of `pip` to use the `python` command,
avoiding discrepancies on systems where the `pip` and `python` commands
are not provided by the same Python installation. In the interest of
consistency, also update the configuration for the project's continuous
integration service.
Recommend additional tooling for users with more advanced needs.
---
.travis.yml | 4 ++--
CONTRIBUTING.md | 8 ++++++--
2 files changed, 8 insertions(+), 4 deletions(-)
diff --git a/.travis.yml b/.travis.yml
index 8403926d14..45bbf5b9be 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,7 +1,7 @@
language: python
install:
- - pip install --requirement tools/generation/requirements.txt
- - pip install --requirement tools/lint/requirements.txt
+ - python -m pip install --requirement tools/generation/requirements.txt
+ - python -m pip install --requirement tools/lint/requirements.txt
script:
- ./tools/scripts/ci_build.sh
- ./tools/generation/test/run.py
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 08c07a2def..a0572e5623 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -277,11 +277,15 @@ p.then(function () {
As above, exceptions that are thrown from a `then` clause are passed to a later `$DONE` function and reported asynchronously.
+## A Note on Python-based tools
+
+This project's internal tooling is built with Python. Contributors seeking to interact with these tools should begin by installing [Python version 2](https://www.python.org/) and [PIP](https://pypi.org/project/pip/). This guide includes instructions for installing packages using PIP directly, but contributors are welcomed to use utilities such as [virtualenv](https://pypi.org/project/virtualenv/), [pyenv](https://github.com/pyenv/pyenv), or [pipenv](https://pypi.org/project/pipenv/) should they have more advanced package management needs.
+
## Linting
Some of the expectations documented here are enforced via a "linting" script. This script is used to validate patches automatically at submission time, but it may also be invoked locally. To do so, first install the required Python packages via the following command:
- pip install --requirement tools/lint/requirements.txt
+ python -m pip install --requirement tools/lint/requirements.txt
Then invoke the following command:
@@ -320,7 +324,7 @@ any other valid frontmatter field | see the frontmatter definitions.
Generated files are managed using the `make.py` Python script located in the root of this repository. To use it, first install the required Python packages via the following command:
- pip install --requirement tools/generation/requirements.txt
+ python -m pip install --requirement tools/generation/requirements.txt
And then issue the following command to create files:
--
GitLab