How to contribute¶

1. Intro¶

We welcome and greatly appreciate contributions of all forms and sizes! Whether it’s updating the documentation, adding small extensions, or implementing new features, every effort is valued.

For substantial changes, please contact us in advance. This allows us to discuss your ideas and guide the development process from the beginning. You can start a conversation by posting an issue on GitHub or by emailing janosg.

To get familiar with the codebase, we recommend checking out our issue tracker for some immediate and clearly defined tasks.

2. Before you start¶

Once you’ve decided to contribute, please review the Styleguide (see the next page) to ensure your work aligns with the project’s coding standards.

We manage new features through Pull Requests (PRs). Contributors work on their local copy of optimagic, modifying and extending the codebase there, before opening a PR to propose merging their changes into the main branch.

Regular contributors gain push access to unprotected branches, which simplifies the contribution process (see Notes below).

3. Step-by-step guide¶

Fork the optimagic repository. This action creates a copy of the repository with write access for you.

Note

For regular contributors: Clone the repository to your local machine and create a new branch for implementing your changes. You can push your branch directly to the remote optimagic repository and open a PR from there.

Clone your forked repository to your disk. This is where you’ll make all your changes.
Open your terminal and execute the following commands from the root directory of your local optimagic repository:
```
$ prek install
```
This activates pre-commit hooks for linting and style formatting.

Note

prek is not managed by pixi and must be installed globally. You can find installation instructions at github.com/j178/prek.

You can then run the test suite with:
```
$ pixi run tests
```
which installs the development dependencies and runs pytest. To run the type checker, use:
```
$ pixi run mypy
```
To see all available pixi tasks, run:
```
$ pixi task list
```
Implement your fix or feature. Use git to add, commit, and push your changes to the remote repository. For more on git and how to stage and commit your work, refer to these online materials.
Contributions are validated in two main ways. We run a comprehensive test suite to ensure compatibility with the existing codebase and employ pre-commit hooks to maintain quality and adherence to our style guidelines. Opening a PR (see below) triggers optimagic’s Continuous Integration (CI) workflow, which runs the full test suite, pre-commit hooks, and other checks on a remote server.

You can also run the test suite locally for debugging.

With prek installed, linters run before each commit. Commits are rejected if any checks fail. Note that some linters may automatically fix errors by modifying the code in-place. Remember to re-stage the files after such modifications.

Tip

Skip the next paragraph if you haven’t worked on the documentation.

Assuming you have updated the documentation, verify that it builds correctly. Run:
```
$ pixi run build-docs
```
This command builds the HTML documentation, saving all files in the docs/build/html directory. You can view the documentation with your preferred web browser by opening docs/build/html/index.html or any other file. Similar to the online documentation, you can navigate to different pages simply by clicking on the links.
Once all tests and hooks pass locally, push your changes to your forked repository and create a pull request through GitHub: Go to the Github repository of your fork. A banner on your fork’s GitHub repository will prompt you to open a PR.

Note

Regular contributors with push access can directly push their local branch to the remote optimagic repository and initiate a PR from there.

Follow the steps outlined in the optimagic PR template to describe your contribution, the problem it addresses, and your proposed solution.

Opening a PR initiates a complete CI run, including the pytest suite, linters, code coverage checks, doctests, and building the HTML documentation. Monitor the CI workflow status on your PR page and make necessary modifications to your code based on the results, iterating until all tests pass.
Request a review from one of the main contributors once all CI tests pass. Address any feedback or suggestions by making the necessary changes and committing them.
After your PR is approved, one of the main contributors will merge it into optimagic’s main branch.