How to Contribute

How to Contribute#

Thank you for your interest in contributing to the project! Contributions are welcome and greatly appreciated. This guide will help you get started.

Reporting Issues#

If you encounter a bug or have a feature request, please open an issue on fschuch/xcompact3d_toolbox#issues. Provide as much detail as possible to help us address the issue.

Setting up the Project#

Prerequisites#

The development workflow is powered by Hatch, which manages Python installations, virtual environments, dependencies, besides builds, and deploys the project to PyPI. See Why Hatch? for more details. Refer to Install Hatch for instructions on how to install it on your operating system.

Ensure you have Python 3.9 or later installed (this can also be done by hatch, take a look at hatch python --help).

Tip

Optionally, configure Hatch to keep virtual environments within the project folder:

hatch config set dirs.env.virtual .venv

Clone the repository#

Fork the repository and clone it to your local machine:

git clone https://github.com/<your-username>/xcompact3d_toolbox.git
cd xcompact3d_toolbox

Run quality assurance checks to ensure you have green lights on your local copy:

hatch run qa

Tip

You can run hatch env show at any time to see the available environments, their features and scripts.

Code Quality Standards#

To ensure quality standards on the codebase, several tools are configured in the project:

mypy for static type checking
ruff as the linter and code formatter
codespell to check spelling
pytest as the test engine
zizmor for static analysis tool for GitHub Actions workflows

pre-commit manages and runs them on isolated environments. These tools are not declared as development dependencies on the project to avoid duplication. Even though it performs checks on the changes for every commit when installed (hatch run pre-commit-install), it is a good practice to run the checks on the whole codebase occasionally (when a new hook is added or on Pull Requests). You can do so by running hatch run check <hook-id>, for instance hatch run check nbstripout. Some of them are available as scripts as a syntax sugar, like hatch run lint, hatch run format, or hatch run type. They check the whole codebase using ruff, ruff-format, and mypy, respectively.

The file pyproject.toml includes configuration for some of the tools, so they can be consumed by your IDE as well. The file .pre-commit-config.yaml includes the configuration for the pre-commit hooks.

The pytest test suite can be run from the default environment with hatch run test or hatch run test-no-cov (the latter without coverage check).

Code examples on docstrings and documentation are tested by the doctest module (configured on the file pyproject.toml). It is integrated with pytest, so the previous test commands will also run the doctests.

To run all the quality checks, you can use the command hatch run qa.

To step up in the game, an extended test environment and the command hatch run test:extended are available to verify the package on different Python versions and under different conditions thanks to the pytest plugins:

pytest-randomly that randomizes the test order;
pytest-rerunfailures that re-runs tests to eliminate intermittent failures;
pytest-xdist that parallelizes the test suite and reduce runtime, to help the previous points that increase the workload;
The file pyproject.toml includes configuration for them.

Continuous Integration#

The workflow ci.yaml performs the verifications on every push and pull request, and deploys the package if running from a valid tag.
pre-commit.ci is integrated on the repo to ensure the pre-commit hooks are checked and up-to-date.
SonarCloud is used to analyze the code quality, code coverage, maintainability, and more.
Dependabot is enabled to keep the dependencies up-to-date (dependabot.yml).

Development Workflow#

Create a Branch: Create a new branch for your feature or bug fix:
```
git checkout -b feature/<your-feature-name>
```
Make Changes: Implement your changes. Follow the coding standards enforced by the project.
Documentation: Update or add docstrings and documentation as needed.
Run Quality Checks: Before committing, ensure your changes pass all checks:
```
hatch run qa
```
Optionally, you can install the pre-commit hooks to run these checks automatically before each commit:
```
hatch run pre-commit-install
```
Commit Changes: Commit your changes with a meaningful message (Conventional Commits are advised):
```
git add .
git commit -m "change: Describe your changes"
```
Push and Open a Pull Request: Push your branch and open a pull request:
```
git push origin feature/<your-feature-name>
```
- Ensure your pull request includes a clear description of the changes.
- Reference any related issues.

Pull Request Labels and Changelog#

We use GitHub’s automated release notes to generate the changelog. Labels on pull requests are critical for organizing the changelog into meaningful categories. Below are the labels we use and their purposes:

Security: For security-related changes (security).
Removed: For features or functionality that has been removed (removed).
Deprecated: For features that are deprecated but still available (deprecated).
Added: For new features or functionality (added).
Changed: For updates or modifications to existing features (changed).
Fixed: For bug fixes (fixed).
Documentation: For changes to documentation (docs).
Internals: For internal changes like refactoring, dependency updates, or chores (chore, refactor, dependencies).
Other Changes: For tags that do not fit into the above categories.

A good pull request title is essential for generating a clear and concise changelog. The title should:

Be descriptive and summarize the change.
Use an imperative tone (e.g., “Add feature X” instead of “Added feature X”).
Avoid vague terms like “Fix issue” or “Update code.”

For example:

✅ “Add support for custom configurations”
✅ “Fix crash when loading large datasets”
❌ “Bug fix”
❌ “Miscellaneous updates”

Creating a New Release#

To create a new release, follow these steps:

Ensure all pull requests for the release are labeled and merged.
Create a new release from GitHub: fschuch/xcompact3d_toolbox
- Based on previous versions, choose the next version number according to the EffVer scheme. The tag matching pattern is set to v*.*.*, for instance, v1.2.3, , v2.3.4a0, , v2.3.4b0, v2.3.4rc0.
- Choose to create a new tag on publish based on version from previous step.
- Click on Generate Release Notes. Modify the release notes as needed.
- Double-check if the new version number is appropriate for the given set of changes.
- Verify if it needs to be set to Pre-release (i.e., its alpha, beta, or release candidate).
- Ensure to select the Save Draft option to have some extra time to double-check all the points above, or to ask for feedback from collaborators.
- Click on Publish Release when ready.
The process can also be triggered from the command line using gh command line tool:
- Check current version:
```
hatch version
```
- Follow previous instruction on how to set the new version number. Start a new release:
```
gh release create <new_version> --generate-notes --draft
```
The CI workflow will automatically test, build and publish the package to PyPI if the tag matches the pattern v*.*.*.

Documentation#

The project uses Jupyter Books to provide a promising approach for interactive tutorials. The documentation source is on the docs folder and can be served locally with hatch run docs:serve, it will be available on http://127.0.0.1:8000. The documentation is also built automatically on the deployment workflow docs.yaml.

Modules and functions docstrings are used to generate the documentation thanks to the sphinx-autodoc and sphinx-napoleon packages.

Useful references:

Miscellaneous#

VSCode Configuration#

The project includes a .vscode folder with a extensions.json file that suggests the extensions to be installed on VSCode. It allows test, debug, auto-format, lint, and a few other functionalities to work directly on your IDE. It also includes a settings.json file that configures the Python extension to use the virtual environment created by Hatch. Remember to set hatch to use the virtual environment within the project folder hatch config set dirs.env.virtual .venv.