From 08f8b67fb7c6806b28c55a46125035116443750b Mon Sep 17 00:00:00 2001 From: Vikas Katariya Date: Fri, 9 Oct 2020 15:26:30 +0100 Subject: [PATCH] docs: Advise on virtual environment usage Advise to use Tox rather than pipenv virtual environment. --- CONTRIBUTING.md | 10 +++++----- DEVELOPMENT.md | 28 ++++++++++------------------ README.md | 5 ++--- docs/howto/mbed-tools-howto.md | 2 +- news/202010091700.doc | 1 + 5 files changed, 19 insertions(+), 27 deletions(-) create mode 100644 news/202010091700.doc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2d03df40..26fd56f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contribution Guide -Mbed OS is an open source project and we really appreciate your contributions to the tools. We are committed to +Mbed OS is an open source project and we really appreciate your contributions to the tools. We are committed to fostering a welcoming community, please see our Code of Conduct, which can be found here: - [Code of Conduct](./CODE_OF_CONDUCT.md) @@ -63,13 +63,13 @@ The `pre-commit` tool allows developers to easily install git hook scripts which must pass in our CI before a PR is merged. Using commit hooks ensures you can't commit code which violates our style and maintainability requirements. -To install the commit hooks for the repository, run: +To install the commit hooks for the repository (assuming you have activated your development environment as described in [the development guide](./DEVELOPMENT.md)), run: + ```bash -$ pipenv install --dev -$ pipenv shell $ pre-commit install ``` -Our code checks and unit tests will now run automatically every time you try to `git commit` to the repository. +Our code checks will now run automatically every time you try to `git commit` to the repository. + If you prefer not to install the hook scripts, you can use ```bash $ pre-commit run diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b88b0843..df8c98bc 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,8 +1,8 @@ # Development and Testing -For development and testing purposes, it is essential to use a virtual environment. It is recommended that `pipenv >= 2018.11.26` is used. +For development and testing purposes, it is essential to use a virtual environment. -## Setup Python and Pipenv +## Setup Python and tox `mbed-tools` is compatible with Python 3.6 or later. @@ -16,16 +16,16 @@ Below are links to guides for correctly setting up a development ready version o On Windows we have also found the [Python Launcher for Windows](https://docs.python.org/3/using/windows.html) to be a reasonable alternative. -After you have set up your Python 3 installation, install pipenv (the `--user` flag is important **never use `sudo` to install Python packages!**) +After you have set up your Python 3 installation, install tox (the `--user` flag is important **never use `sudo` to install Python packages!**) ```bash -pip install --user pipenv +python(3) -m pip install --user tox ``` -Check that pipenv is in the binary path +Check that tox is in the binary path ```bash -pipenv --version +tox --version ``` If not, find the user base binary directory @@ -49,25 +49,17 @@ Clone the `mbed-tools` GitHub repository git clone git@github.com:ARMmbed/mbed-tools.git ``` -Setup Pipenv to use Python 3 and install package development dependencies: +Set up the development environment using tox (tox will create a development environment at mbed-tools/.venv): ```bash cd mbed-tools/ -pipenv --three -pipenv install --dev --skip-lock +tox -e dev +source .venv/bin/activate ``` -You may omit the `--skip-lock` flag. Note creating the `Pipfile.lock` can take a long time! - ## Unit Tests, Code Formatting and Static Analysis -Shell into the virtual environment you have just created: - -```bash -pipenv shell -``` - -Run `pre-commit` to run unit tests and static code analysis checks: +After you have activated your development environment, run `pre-commit` to run unit tests and static code analysis checks: ```bash pre-commit run --all-files diff --git a/README.md b/README.md index 5acd5e7f..013e9446 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ The version scheme used follows [PEP440](https://www.python.org/dev/peps/pep-044 - `..` -Beta releases are used to give early access to new functionality, for testing and to get feedback on experimental +Beta releases are used to give early access to new functionality, for testing and to get feedback on experimental features. As such these releases may not be stable and should not be used for production. Additionally any interfaces introduced in a beta release may be removed or changed without notice. For **beta** releases the version will look as follows: @@ -48,8 +48,7 @@ follows: ## Installation -It is recommended that a virtual environment such as [Pipenv](https://github.com/pypa/pipenv/blob/master/README.md) is -used for all installations to avoid Python dependency conflicts. +We recommend installing `mbed-tools` in a Python virtual environment to avoid dependency conflicts. To install the most recent production quality release use: diff --git a/docs/howto/mbed-tools-howto.md b/docs/howto/mbed-tools-howto.md index 88df1445..e89dda50 100644 --- a/docs/howto/mbed-tools-howto.md +++ b/docs/howto/mbed-tools-howto.md @@ -8,7 +8,7 @@ You'll still need Mbed CLI for older versions of Mbed OS. You can install both t Mbed Tools is Python based, so you can install it with pip. -**Tip:** We recommend using a virtual environment such as [Pipenv](https://github.com/pypa/pipenv/blob/master/README.md) to avoid Python dependency conflicts. +**Tip:** We recommend using a virtual environment to avoid Python dependency conflicts. ## Prerequisite diff --git a/news/202010091700.doc b/news/202010091700.doc new file mode 100644 index 00000000..1c1293bd --- /dev/null +++ b/news/202010091700.doc @@ -0,0 +1 @@ +Advise on using Tox rather than pipenv virtual environment