mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-21 10:17:59 -05:00
Kill Pipfile, update dependencies, and add dep bumping tools (#2806)
### Replacement for pipenv's environment setup First of all, there's a new Make recipe for all devs and contributors on both Windows and Posix, `make setupenv`, which is kind of a replacement for `pipenv install --dev`. It creates a virtual environment in `.venv` using the inbuilt `venv` module, clearing out any existing virtual environment if needed first. Then it installs all dev dependencies using our new `dev-requirements.txt` file. `CONTRIBUTING.md` has been updated to reflect all of this. ### Dependency version bumping tool Secondly, I've added a python script, `tools/bumpdeps.py` to help with bumping dependency versions. It has its own Make recipe too, `make bumpdeps`. This script won't work on Windows (yet). It reads the `tools/primary_deps.ini` file, which contains the primary requirements of Red and its extras with loose version specifiers, and outputs all pinned dependencies, in `setup.cfg` format. It's not a foolproof dependency resolver, it's quite simple, but it's bound to help out a lot. It'll try to give warnings if there might be a version conflict, but updating `setup.cfg` with its output and then doing `pip install -r dev-requirements.txt` will allow pip to issue warnings if something is conflicting. So to add a new dependency, add it to `tools/primary_deps.ini` in the appropriate place, and either use `make bumpdeps` to completely update all dependencies, or simply add it to `setup.cfg` manually with its sub-dependencies, and all versions pinned. ### Sphinx 2.1.2 (docs changes) The sphinx update brought along the ability to disable type annotations being rendered in function and method signatures, and I have gladly gone and done that. Type annotations should already be specified under the "Parameters" section, and the way sphinx renders them in function signatures makes them much harder to read. Also, documented classes will now display what classes they inherit from. Signed-off-by: Toby Harradine <tobyharradine@gmail.com>
This commit is contained in:
32
.github/CONTRIBUTING.md
vendored
32
.github/CONTRIBUTING.md
vendored
@@ -56,24 +56,27 @@ The following requirements must be installed prior to setting up:
|
||||
- Python 3.7.0 or greater
|
||||
- git
|
||||
- pip
|
||||
- pipenv
|
||||
|
||||
If you're not on Windows, you can optionally install [pyenv](https://github.com/pyenv/pyenv), which will help you run tests for different python versions.
|
||||
If you're not on Windows, you should also have GNU make installed, and you can optionally install [pyenv](https://github.com/pyenv/pyenv), which can help you run tests for different python versions.
|
||||
|
||||
1. Fork and clone the repository to a directory on your local machine.
|
||||
2. Open a command line in that directory and execute the following commands:
|
||||
2. Open a command line in that directory and execute the following command:
|
||||
```bash
|
||||
pip install pipenv
|
||||
pipenv install --dev
|
||||
make setupenv
|
||||
```
|
||||
Red, its dependencies, and all required development tools, are now installed to a virtual environment. Red is installed in editable mode, meaning that edits you make to the source code in the repository will be reflected when you run Red.
|
||||
3. Activate the new virtual environment with the command:
|
||||
```bash
|
||||
pipenv shell
|
||||
```
|
||||
From here onwards, we will assume you are executing commands from within this shell. Each time you open a new command line, you should execute this command first.
|
||||
Red, its dependencies, and all required development tools, are now installed to a virtual environment located in the `.venv` subdirectory. Red is installed in editable mode, meaning that edits you make to the source code in the repository will be reflected when you run Red.
|
||||
3. Activate the new virtual environment with one of the following commands:
|
||||
- Posix:
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
- Windows:
|
||||
```powershell
|
||||
.venv\Scripts\activate
|
||||
```
|
||||
Each time you open a new command line, you should execute this command first. From here onwards, we will assume you are executing commands from within this activated virtual environment.
|
||||
|
||||
Note: If you haven't used `pipenv` before but are comfortable with virtualenvs, just run `pip install pipenv` in the virtualenv you're already using and invoke the command above from the cloned Red repo. It will do the correct thing.
|
||||
**Note:** If you're comfortable with setting up virtual environments yourself and would rather do it manually, just run `pip install -r dev-requirements.txt` after setting it up.
|
||||
|
||||
### 4.2 Testing
|
||||
We've recently started using [tox](https://github.com/tox-dev/tox) to run all of our tests. It's extremely simple to use, and if you followed the previous section correctly, it is already installed to your virtual environment.
|
||||
@@ -95,12 +98,13 @@ Our style checker of choice, [black](https://github.com/ambv/black), actually ha
|
||||
Use the command `black --help` to see how to use this tool. The full style guide is explained in detail on [black's GitHub repository](https://github.com/ambv/black). **There is one exception to this**, however, which is that we set the line length to 99, instead of black's default 88. When using `black` on the command line, simply use it like so: `black -l 99 -N <src>`.
|
||||
|
||||
### 4.4 Make
|
||||
You may have noticed we have a `Makefile` and a `make.bat` in the top-level directory. For now, you can do two things with them:
|
||||
You may have noticed we have a `Makefile` and a `make.bat` in the top-level directory. For now, you can do three things with them:
|
||||
1. `make reformat`: Reformat all python files in the project with Black
|
||||
2. `make stylecheck`: Check if any `.py` files in the project need reformatting
|
||||
3. `make setupenv`: Set up a new virtual environment in the `.venv` subdirectory, and install Red and its dependencies. If one already exists, it is cleared out and replaced.
|
||||
|
||||
### 4.5 Keeping your dependencies up to date
|
||||
Whenever you pull from upstream (V3/develop on the main repository) and you notice the file `Pipfile.lock` has been changed, it usually means one of the package dependencies have been updated, added or removed. To make sure you're testing and formatting with the most up-to-date versions of our dependencies, run `pipenv install --dev` again.
|
||||
Whenever you pull from upstream (V3/develop on the main repository) and you notice either of the files `setup.cfg` or `dev-requirements.txt` have been changed, it can often mean some package dependencies have been updated, added or removed. To make sure you're testing and formatting with the most up-to-date versions of our dependencies, run `make setupenv` to recreate your virtual environment. You could also simply do `pip install -Ur dev-requirements.txt`, but you will still have any dependencies which may have been removed previously.
|
||||
|
||||
### 4.6 To contribute changes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user