Skip to content

development.md

Latest commit

 

History

History
190 lines (141 loc) · 6.56 KB

development.md

File metadata and controls

190 lines (141 loc) · 6.56 KB

(sec_development)=

Development

We welcome all contributors! Contributions to demes typically take the form of "pull requests" against our git repository.

Requirements

Demes aims to have minimal dependencies when used as a library by other projects. However, additional dependencies are required during development, as developers regularly run the test suite, build the documentation, and assess whether their code changes conform to style guidelines. The pyproject.toml file in the top-level folder lists all development dependencies, which can be installed using uv. In the following documentation, we assume the reader has cloned the source repository and installed the developer requirements as follows.

To install uv, take one of the following paths:

  • Follow that project's documentation.
  • Use the package manager of your choice on your operating system.

Then:

# Clone the repository.
git clone https://github.com/popsim-consortium/demes-python.git
cd demes-python
# update the demes-spec submodule
git submodule update --init
# Use uv to install dependencies and build the demes package:
uv sync --all-groups

You may now do things like run the test suite:

uv run python -m pytest tests

The --all-groups flag will install all build dependencies, runtime dependencies, and developer dependencies listed in dependency-groups in pyproject.toml. If you want to only install specific dependency groups, do so following the uv documentation.

Non-developer requirements are listed in the `dependency-groups` section
of the ``pyproject.toml`` file in the top-level folder of the sources.

Updating uv.lock ("dependency management")

If any of the following occur in pyproject.toml, then the contents of uv.lock may no longer by valid:

  • Changing a dependency version number pin
  • Adding/removing a dependency
  • Changing the supported range of Python versions
  • Changing the set of supported operating systems / platforms.

To rebuild the lock file:

uv lock

Then, commit the new lock file!

Updating individual packages in uv.lock

One may occastionally need to update the locked version of a specific dependency. Currently, this happens via arguments to uv lock. Counsult the uv documentation for details.

Continuous integration (CI)

After a pull request is submitted, an automated process known as continuous integration (CI) will:

  • assess if the proposed changes conform to style guidelines (known as lint checks),
  • run the test suite,
  • and build the documentation.

The CI process uses GitHub Actions and the configuration files detailing how these are run can be found under the .github/workflows/ folder of the sources.

Lint checks

The following tools are run during the linting process:

  • black, a code formatter (code is only checked during CI, not reformatted),
  • flake8, a PEP8 code-style checker,
  • mypy, a static type checker.

Each of these tools can also be run manually from the top-level folder of the sources. The setup.cfg file includes some project-specific configuration for each of these tools, so running them from the command line should match the behaviour of the CI checks.

For example, to reformat the code with black after making changes to the demes/demes.py file (command output shown as comments):

black .
# reformatted /home/grg/src/demes/demes/demes.py
# All done! ✨ 🍰 ✨
# 1 file reformatted, 14 files left unchanged.

Similarly, one can check conformance to PEP8 style guidelines by running flake8 (without parameters), and check type annotations by running mypy (also without parameters).

Pre-commit

To simplify the process of running each of the linter tools, we also include a configuration for the pre-commit program. If you prefer not to run each of the commands above manually, install the pre-commit Python package and then run pre-commit install from the top-level folder of your cloned demes repository. Now when you try to commit changes, the lint checks will be performed automatically. If pre-commit made changes to the files when you tried to commit, you'll need to stage those changes and try again. E.g. git add -u; git commit. See the pre-commit documentation for more details.

Test suite

A suite of tests is included in the tests/ folder. The CI process uses the pytest tool to run the tests, which can also be run manually from the top-level folder of the sources.

python -m pytest -v tests --cov=demes --cov-report=term-missing

or

uv run python -m pytest -v tests --cov=demes --cov-report=term-missing

This will produce lots of output, indicating which tests passed, and which failed (if any). There may also be warnings. Any warnings that are triggered by code in demes (rather than third-party libraries), should be fixed.

It is expected that new code contributions will be tested by the introduction of new tests in the test suite. While we don't currently have any strict requirements for code coverage, more is better. Furthermore, we encourage contributions that improve, or expand on, the existing suite of tests.

Building the documentation

The demes documentation is built with jupyter-book, which uses sphinx. Much of the documentation is under the docs/ folder, written in the MyST flavour of Markdown, and is configured in the docs/_config.yml file. In contrast, the API documentation is automatically generated from "docstrings" in the Python code that use the reStructuredText format. To build the documentation locally, run make from the docs/ folder.

cd docs
make

If this was successful, the generated documentation can be viewed in a browser by navigating to the docs/_build/html/index.html file. It is expected that new code contributions will be accompanied by relevant documentation (e.g. a new function will include a docstring).

We strongly encourage contributions that improve the demes documentation, such as fixing typos and grammatical errors, or making the documentation clearer and/or more accessible.

Releasing a new version