Skip to content

Contributing to AsymmeTree

Thank you for your interest in contributing to AsymmeTree! This page provides guidelines for contributing to the project, including how to set up your development environment and submit changes.

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

In short:

  • Be respectful and inclusive in all interactions.
  • Harassment, discrimination, and personal attacks of any kind will not be tolerated.
  • Focus feedback on ideas and code, not on individuals.

If you witness or experience unacceptable behavior, please report it by opening a GitHub issue or by contacting the maintainer directly.

Reporting issues

If you encounter a bug or have a feature request, please check the issue tracker to see if there is an existing issue for it. If not, please open a new issue with a clear and descriptive title and a detailed description of the problem or feature request. If applicable, please include steps to reproduce the issue, expected and actual behavior, and any relevant screenshots or error messages.

Pull Request workflow

Please keep pull requests focused and reasonably scoped — one feature or bug fix per PR is preferred. Target the main branch for all pull requests.

External contributors (fork-based workflow)

If you do not have write access to the repository, please use the standard fork-based workflow:

  1. Fork the repository on GitHub.
  2. Clone your fork locally and add the upstream remote: 
    git clone https://github.com/<YOUR_USERNAME>/AsymmeTree.git
cd AsymmeTree
git remote add upstream https://github.com/david-schaller/AsymmeTree.git
  3. Create a feature branch off main: 
    git fetch upstream
git checkout -b my-feature upstream/main
  4. Make your changes, commit them, and push to your fork: 
    git push origin my-feature
  5. Before opening a PR, sync your branch with upstream to avoid merge conflicts: 
    git fetch upstream
git rebase upstream/main
  6. Open a pull request from <YOUR_USERNAME>/AsymmeTree:my-feature against david-schaller/AsymmeTree:main on GitHub.

Collaborators with repository access

If you have write access to the repository, you can work directly on a branch in the main repository without forking:

  1. Create a feature branch off main: 
    git fetch origin
git checkout -b my-feature origin/main
  2. Make your changes, commit them, and push: 
    git push origin my-feature
  3. Open a pull request against the main branch on GitHub.

All contributors

Regardless of workflow, when opening a pull request please:

  • Provide a clear title and description summarizing the changes.
  • Reference any related issues (e.g., Closes #42).
  • Request a review from a maintainer.
  • Ensure branches are named descriptively (e.g., fix/sampling-bug or feature/new-evolution-model).
  • Ensure that commit messages are concise and ideally follow the format: <type>(<scope>): <description>, where <type> is one of feat, fix, docs, style, refactor, perf, or test.

The pull request will be reviewed and you may be asked to make further changes before it is merged.

Changelog

Please update CHANGELOG.md when contributing changes. Add a new ## [Unreleased] section at the top of the file if one does not already exist, and add your entry there.

Entries are organized into subsections by change type. Use the following categories as applicable:

Category Description
🌟 Features New features or enhancements
🚨 Breaking changes Changes that break backward compatibility
🐛 Bug fixes Bug fixes
⚡️ Performance Performance improvements
♻️ Refactorings Internal refactorings without behavior changes
🎨 Style Code style and formatting changes
📚 Documentation Documentation updates
📦 Build Build system and dependency changes

Each entry should be a concise bullet point describing the change and, if applicable, reference the relevant issue or pull request number.

Checklist before submitting a Pull Request

When submitting a pull request, you agree that your contribution will be licensed under the same license as AsymmeTree (MIT License).

Before submitting your pull request, make sure that:

Note

After your pull request is merged, the maintainer will include your changes in the next release. If you need a release sooner, feel free to open a GitHub issue or contact the maintainer directly.

Development environment setup with uv

If you want to contribute, please use the package and project manager uv. See this page for installation instructions.

To set up uv, navigate to the root directory of your local AsymmeTree repository (or your fork of it — see Pull Request workflow) and create a new virtual environment that is managed by uv:

cd <MY_PATH_TO>/AsymmeTree
uv sync

A new virtual environment will be created in the .venv directory of your local AsymmeTree repository, and all dependencies of AsymmeTree will be installed in this virtual environment. To activate this virtual environment, run the following command:

# On Linux or MacOS
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Managing dependencies

Dependencies are declared in pyproject.toml. Runtime dependencies are listed under [project] > dependencies, and optional dependency groups (e.g., docs) are listed under [dependency-groups].

To add a new runtime dependency, use:

uv add <package>

To add a dependency to a specific group (e.g., docs), use:

uv add --group docs <package>

To remove a dependency, use:

uv remove <package>

These commands update pyproject.toml and uv.lock automatically. Please commit both files when adding or changing dependencies.

Code style and linting

General guidelines

Please follow the Google style guide for Python code style and documentation. Additionally, please adhere to the following guidelines:

  • Keep line lengths to a maximum of 100 characters.
  • Use type hints for all function arguments and return types.
  • The Returns section in docstring should use an additional indentation level for text that does not fit in a single line to ensure proper formatting in the generated documentation. In case of multiple return values, start the description of each return value on a new line using the same indentation level as the first return value.
  • f-strings should be used for string formatting whenever possible.

Make sure to write clear and concise docstrings for all functions, classes, and modules.

pre-commit

Please use pre-commit for automated code formatting and linting. To install it and initialize it for your local AsymmeTree repository, follow these steps:

Install uv as described above. Run the following command (after which you should be able to run pre-commit from anywhere):

uv tool install pre-commit --with pre-commit-uv

Navigate to the root directory of your local AsymmeTree repository and install pre-commit as a git hook in the AsymmeTree repository:

cd <MY_PATH_TO>/AsymmeTree
pre-commit install

After this, pre-commit will automatically run the configured hooks (e.g., code formatting and linting) before each commit, ensuring that your code adheres to the project's coding standards.

Running Tests

To run the tests for AsymmeTree, make sure you have set up your development environment with uv as described in the previous section.

Then, you can run the tests using the following command:

uv run tests/all_tests.py

Note

The project intends to migrate to pytest and introduce a GitHub Actions workflow that automatically runs tests on new commits and pull requests.

Documentation

Setting up MkDocs

The documentation of AsymmeTree is maintained in the docs folder of the repository and is built using MkDocs.

To install it, run the following command:

cd <MY_PATH_TO>/AsymmeTree
uv sync --group docs

# or if you want to install all dependency groups, including the `docs` group:
uv sync --all-groups

After installing the dependencies, you can serve the documentation locally by running the following command in the root directory of your local AsymmeTree repository:

uv run mkdocs serve

This will start a local development server, and you can access the documentation by navigating to the URL displayed in the terminal.

The documentation is automatically deployed to GitHub Pages:

Trigger Version URL
Publishing a release Latest release (stable) https://david-schaller.github.io/AsymmeTree/
Push or merge to main Development (may contain unreleased changes) https://david-schaller.github.io/AsymmeTree/dev/

Pull requests are checked with mkdocs build --strict but not deployed.

Updating the documentation

When contributing to AsymmeTree, please make sure to update the documentation accordingly.

The documentation files in the docs folder are written in Markdown and are organized as follows:

  • index.md: The main page of the documentation.
  • installation.md: Instructions for installing AsymmeTree.
  • guide/: A folder containing user guides and tutorials for using AsymmeTree.
  • api/: A folder containing the API reference for AsymmeTree.
  • citation.md: Information on how to cite AsymmeTree in academic publications.
  • contributing.md: This file, containing guidelines for contributing to AsymmeTree.

The API reference is mostly generated from the docstrings in the code, but you may need to update the corresponding files in the docs/api folder to include new modules or reflect changes in the package structure when contributing to AsymmeTree. If you add a new function or class, please add a docstring to it following the Google style guide.

The user guides and tutorials in the docs/guide folder are mostly written manually, so you will need to update them manually when contributing to AsymmeTree if you add new features or want to provide new guides or tutorials.

If you add or restructure documentation files, please make sure to update the nav section in the mkdocs.yml file accordingly to include the new files and reflect the new structure.