Development Environment
Clone the repo you just forked on GitHub to your local machine. Configure your repo to point to both “upstream” (the main conda repo) and your fork (“origin”). For detailed directions, see below:
Bash (macOS, Linux, Windows)
# choose the repository location # warning: not the location of an existing conda installation! $ CONDA_PROJECT_ROOT="$HOME/conda" # clone the project # replace `your-username` with your actual GitHub username $ git clone [email protected]:your-username/conda "$CONDA_PROJECT_ROOT" $ cd "$CONDA_PROJECT_ROOT" # set the `upstream` as the the main repository $ git remote add upstream [email protected]:conda/conda
cmd.exe (Windows)
# choose the repository location # warning: not the location of an existing conda installation! > set "CONDA_PROJECT_ROOT=%HOMEPATH%\conda" # clone the project # replace `your-username` with your actual GitHub username > git clone [email protected]:your-username/conda "%CONDA_PROJECT_ROOT%" > cd "%CONDA_PROJECT_ROOT%" # set the `upstream` as the main repository > git remote add upstream [email protected]:conda/conda
One option is to create a local development environment and activate that environment
Bash (macOS, Linux, Windows)
$ source ./dev/start
cmd.exe (Windows)
> .\dev\start.bat
This command will create a project-specific base environment (see
devenv
in your repo directory after running this command). If the base environment already exists this command will simply activate the already-createddevenv
environment.To be sure that the conda code being interpreted is the code in the project directory, look at the value of
conda location:
in the output ofconda info --all
.Alternatively, for Linux development only, you can use the same Docker image the CI pipelines use. Note that you can run this from all three operating systems! We are using
docker compose
, which provides three actions for you:unit-tests
: Run all unit tests.integration-tests
: Run all integration tests.interactive
: You are dropped in a pre-initialized Bash session, where you can run all yourpytest
commands as required.
Use them with
docker compose run <action>
. For example:Any shell (macOS, Linux, Windows)
$ docker compose run unit-tests
This builds the same Docker image as used in continuous integration from the Github Container Registry and starts
bash
with the conda development mode already enabled. By default, it will use Python 3.9 installation.If you need a different Python version, set a
CONDA_DOCKER_PYTHON
environment variable like this to rebuild the image. You might need to add--no-cache
to make sure the image is rebuilt.Bash (macOS, Linux, Windows)
$ CONDA_DOCKER_PYTHON=3.8 docker compose build --no-cache unit-tests
cmd.exe (Windows)
> set CONDA_DOCKER_PYTHON=3.8 && docker compose build --no-cache unit-tests && set "CONDA_DOCKER_PYTHON="
The next time you run
docker compose run <task>
you will use the new image. If you want to revert to the version you were previously using, you need to rebuild the image again.
The
conda
repository will be mounted to/opt/conda-src
, so all changes done in your editor will be reflected live while the Docker container is running.
Static Code Analysis
This project is configured with pre-commit to automatically run linting and other static code analysis on every commit. Running these tools prior to the PR/code review process helps in two ways:
it helps you by automating the nitpicky process of identifying and correcting code style/quality issues
it helps us where during code review we can focus on the substance of your contribution
Feel free to read up on everything pre-commit related in their docs but we’ve included the gist of what you need to get started below:
Bash (macOS, Linux, Windows)
# reuse the development environment created above
$ source ./dev/start
# or start the Docker image in interactive mode
# $ docker compose run interactive
# install pre-commit hooks for conda
$ cd "$CONDA_PROJECT_ROOT"
$ pre-commit install
# manually running pre-commit on current changes
# note: by default pre-commit only runs on staged files
$ pre-commit run
# automatically running pre-commit during commit
$ git commit
cmd.exe (Windows)
:: reuse the development environment created above
> .\dev\start.bat
:: or start the Docker image in interactive mode
:: > docker compose run interactive
:: install pre-commit hooks for conda
> cd "%CONDA_PROJECT_ROOT%"
> pre-commit install
:: manually running pre-commit on current changes
:: note: by default pre-commit only runs on staged files
> pre-commit run
:: automatically running pre-commit during commit
> git commit
Beware that some of the tools run by pre-commit can potentially modify the code (see black, blacken-docs, and darker). If pre-commit detects that any files were modified it will terminate the commit giving you the opportunity to review the code before committing again.
Strictly speaking using pre-commit on your local machine for commits is optional (if you don’t install pre-commit you will still be able to commit normally). But once you open a PR to contribue your changes, pre-commit will be automatically run at which point any errors that occur will need to be addressed prior to proceeding.
Testing
We use pytest to run our test suite. Please consult pytest’s docs for detailed instructions but generally speaking all you need is the following:
Bash (macOS, Linux, Windows)
# reuse the development environment created above
$ source ./dev/start
# or start the Docker image in interactive mode
# $ docker compose run interactive
# run conda's unit tests using GNU make
$ make unit
# or alternately with pytest
$ pytest -m "not integration" conda tests
# or you can use pytest to focus on one specific test
$ pytest tests/test_create.py -k create_install_update_remove_smoketest
cmd.exe (Windows)
:: reuse the development environment created above
> .\dev\start.bat
:: or start the Docker image in interactive mode
:: > docker compose run interactive
:: run conda's unit tests with pytest
> pytest -m "not integration" conda tests
:: or you can use pytest to focus on one specific test
> pytest tests\test_create.py -k create_install_update_remove_smoketest
Note: Some integration tests require you build a package with conda-build beforehand.
This is taking care of if you run docker compose run integration-tests
, but you need
to do it manually in other modes:
Bash (macOS, Linux, Windows)
$ conda install conda-build
$ conda-build tests/test-recipes/activate_deactivate_package tests/test-recipes/pre_link_messages_package
Check dev/linux/integration.sh
and dev\windows\integration.bat
for more details.