How to set up your development environment

This guide will show you how to prepare your local environment for cogent3 development, including how to retrieve a local copy of the cogent3 codebase and installing the necessary tools and dependencies.

• Choosing the right setup
• How to get a local copy of the code
• How to install a python version and development tools
• Testing the cogent3 development installation

Choosing the right setup

I need to make small changes to documentation

If you are addressing issues that do not require code changes, such as small edits to documentation or README.md files, installing the development environment may not be necessary.

In this case, you only need to get a local copy of the code and skip to the following:

• The development workflow
• Contributing documentation

Should I develop natively or with Docker?

For development, we currently support using a native Python environment or a Docker container. There are pros and cons for both, but the short answer to selecting one is:

If you already use conda/pip/venv, use the native environment.

For the native install, follow the rest of the page.

Using Docker may be useful if you need to develop on a system with restricted permissions. In this case, it may be easier to request support for Docker hosting from your IT department, compared to all the components for the native install. These are all packaged up in the container for you.

To use Docker, refer to Developing cogent3 in a docker container.

How to get a local copy of the code

We recommend setting up ssh keys access on GitHub for the project and uploading it. It makes communicating with the repo much easier!

On GitHub, fork the Cogent3 repository.

Then, get a local copy of the forked cogent3 repo by cloning (via ssh):

git clone git@github.com:<YOUR_GITHUB_USERNAME>/cogent3.git Cogent3

Note

We use Cogent3 when referring to the (root of the) repository folder and cogent3 when referring to the Python package itself, which lives in Cogent3/src/cogent3. This helps us distinguish the project as a whole and the Python codebase.

To be able to sync your local changes with the original repository, specify a new remote upstream repository:

cd Cogent3/
git remote add upstream https://github.com/cogent3/cogent3.git

Verify the new upstream repository was added successfully with git remote -v :

origin    git@github.com:<YOUR_GITHUB_USERNAME>/cogent3.git (fetch)
origin    git@github.com:<YOUR_GITHUB_USERNAME>/cogent3.git (push)
upstream  https://github.com/cogent3/cogent3.git (fetch)
upstream  https://github.com/cogent3/cogent3.git (push)

How to install a python version and development tools

Create a new conda environment with a specifc python version to develop with. Here, 3.12 will be used as an example:

conda create -n c312 python=3.12
conda activate c312

Install cogent3 in "develop mode" with all the necessary dependencies:

cd path/to/Cogent3
pip install flit
flit install -s --python `which python`

Testing the cogent3 development installation

To verify that cogent3 has been installed correctly, run the test-suite for the python version specified in your conda install with:

cd Cogent3/
pytest -n auto

Unit tests will be run for each module, and if successful, the final line of the output should have no fails. (xfails are permitted)

Once your development environment is set up, you are ready to move on to The development workflow!

< Previous: Code of Conduct                       Next: The development workflow >