Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
407 lines (267 loc) · 9.43 KB

CONTRIBUTING.md

File metadata and controls

407 lines (267 loc) · 9.43 KB

Contributing to EasyUtilities

Thank you for your interest in contributing to EasyUtilities!

This guide explains how to:

  • Report issues
  • Contribute code
  • Improve documentation
  • Suggest enhancements
  • Interact with the EasyScience community

Whether you are an experienced developer or contributing for the first time, this document walks you through the entire process step by step.

Please make sure you follow the EasyScience organization-wide Code of Conduct.

Table of Contents

How to Interact With This Project

If you are not planning to modify the code, you may want to:

If you plan to contribute code or documentation, continue below.

1. Understanding the Development Model

Before you start coding, it is important to understand how development works in this project.

Branching Strategy

We use the following branches:

  • master — stable releases only
  • develop — active development branch
  • Short-lived branches — one branch per contribution

All normal contributions must target the develop branch.

This means:

  • Do not open Pull Requests against master
  • Always create your branch from develop
  • Always target develop when opening a Pull Request

See ADR easyscience/.github#12 for full details on the branching strategy.

2. Getting the Code

2.1. If You Are an External Contributor

If you are not a core maintainer of this repository, follow these steps.

  1. Open the repository page: https://github.com/easyscience/utils

  2. Click the Fork button (top-right corner). This creates your own copy of the repository.

  3. Clone your fork locally:

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

  4. Add the original repository as upstream:

    git remote add upstream https://github.com/easyscience/utils.git

  5. Switch to the develop branch and update it:

    git fetch upstream
git checkout develop
git pull upstream develop

If you have contributed before, make sure your local develop branch is up to date before starting new work. You can update it with:

git fetch upstream
git pull upstream develop

This ensures you are working on the latest version of the project.

2.2. If You Are a Core Team Member

Core team members do not need to fork the repository. You can create a new branch directly from develop, but the rest of the workflow remains the same.

3. Setting Up the Development Environment

You need:

  • Git
  • Pixi

EasyScience projects use Pixi to manage the development environment.

To install Pixi, follow the official instructions: https://pixi.prefix.dev/latest/installation/

You do not need to manually install Python. Pixi automatically:

  • Creates the correct Python environment
  • Installs all required dependencies
  • Installs development tools (linters, formatters, test tools)

Set up the environment:

pixi install
pixi run post-install

After this step, your development environment is ready.

See ADR easyscience/.github#63 for more details about this decision.

4. Creating a Branch

Never work directly on develop.

Create a new branch:

git checkout -b my-change

Use a clear and descriptive name, for example:

  • improve-solver-speed
  • fix-boundary-condition
  • add-tutorial-example

Clear branch names make reviews and history easier to understand.

5. Implementing Your Changes

While developing:

  • Make small, logical commits
  • Write clear and descriptive commit messages
  • Follow the Google docstring convention
  • Add or update unit tests if behavior changes

Example:

git add .
git commit -m "Improve performance of time integrator for large systems"

Run tests locally:

pixi run unit-tests

Running tests frequently is strongly recommended.

6. Code Quality Checks

Before opening a Pull Request, always run:

pixi run check

This command runs:

  • Formatting checks
  • Linting
  • Docstring validation
  • Notebook checks
  • Unit tests
  • Other project validations

A successful run should look like this:

pixi run pyproject-check...................................Passed
pixi run py-lint-check.....................................Passed
pixi run py-format-check...................................Passed
pixi run nonpy-format-check................................Passed
pixi run docs-format-check.................................Passed
pixi run notebook-format-check.............................Passed
pixi run unit-tests........................................Passed

If something fails, read the error message carefully and fix the issue.

You can run individual checks, for example:

pixi run py-lint-check

Some formatting issues can be fixed automatically:

pixi run fix

If everything is correctly formatted, you will see:

✅ All code auto-formatting steps have been applied.

This indicates that the auto-formatting pipeline completed successfully. If you do not see this message and no error messages appear, try running the command again.

If errors are reported, resolve them and re-run:

pixi run check

All checks must pass before your Pull Request can be merged.

If you are unsure how to fix an issue, ask for help in your Pull Request discussion.

7. Opening a Pull Request

Push your branch:

git push origin my-change

On GitHub:

  • Click Compare & Pull Request
  • Ensure the base branch is develop
  • Write a clear and concise title
  • Add a description explaining what changed and why
  • Add the required [scope] label

Pull Request Title

The PR title appears in release notes and changelogs. It should be concise and informative.

Good examples:

  • Improve performance of time integrator for large systems
  • Fix incorrect boundary condition handling in solver
  • Add adaptive step-size control to ODE solver
  • Add tutorial for custom model configuration
  • Refactor solver API for improved readability

Required [scope] Label

Each Pull Request must include one [scope] label:

Label Description
[scope] bug Bug report or fix (major.minor.PATCH)
[scope] documentation Documentation-only changes (major.minor.patch.POST)
[scope] enhancement Adds or improves features (major.MINOR.patch)
[scope] maintenance Code/tooling cleanup without feature or bug fix (major.minor.PATCH)
[scope] significant Breaking or major changes (MAJOR.minor.patch)

See ADR easyscience/.github#33 for full versioning rules.

8. Continuous Integration (CI)

After opening a Pull Request:

  • Automated checks run automatically
  • You will see green checkmarks or red crosses

If checks fail:

  1. Open the failing check
  2. Read the logs
  3. Fix the issue locally
  4. Run pixi run check
  5. Push your changes

The Pull Request updates automatically.

9. Code Review

All Pull Requests are reviewed by at least one core team member.

Code review is collaborative and aims to improve quality.

Do not take comments personally — they are meant to help.

To update your PR:

git add .
git commit -m "Address review comments"
git push

10. Documentation Contributions

If your change affects users, update the documentation.

This may include:

  • API documentation
  • Examples
  • Tutorials
  • Jupyter notebooks

Preview documentation locally:

pixi run docs-serve

Open the URL shown in the terminal to review your changes.

11. Reporting Issues

If you find a bug but do not want to fix it:

  • Search existing issues first
  • Provide clear reproduction steps
  • Include logs and environment details

Clear issue reports help maintainers significantly.

12. Security Issues

Do not report security vulnerabilities publicly.

If you discover a potential vulnerability, contact the maintainers privately.

13. Releases

Releases are created by merging develop into master.

Once your contribution is merged into develop, it will be included in the next stable release.

Thank you for contributing to EasyUtilities and the EasyScience ecosystem!