# 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](https://github.com/easyscience/.github/blob/master/CODE_OF_CONDUCT.md).

---

## How to Interact With This Project

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

- 🐞 Report a bug — see [Reporting Issues](#11-reporting-issues)
- 🛡 Report a security issue — see
  [Security Issues](#12-security-issues)
- 💬 Ask a question or start a discussion at
  [Project Discussions](https://github.com/easyscience/utils/discussions)

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:

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

4. Add the original repository as `upstream`:

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

5. Switch to the `develop` branch and update it:

   ```bash
   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:

```bash
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:

```bash
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:

```bash
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:

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

Run tests locally:

```bash
pixi run unit-tests
```

Running tests frequently is strongly recommended.

---

## 6. Code Quality Checks

Before opening a Pull Request, always run:

```bash
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:

```bash
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:

```bash
pixi run py-lint-check
```

Some formatting issues can be fixed automatically:

```bash
pixi run fix
```

If everything is correctly formatted, you will see:

```text
✅ 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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!
