How to contribute#

1. Intro#

We welcome and greatly appreciate contributions of all forms and sizes! Whether it’s updating the online 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 estimagic, 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#

  1. Fork the estimagic 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 estimagic repository and open a PR from there.

  1. Clone your forked repository to your disk. This is where you’ll make all your changes.

  2. Open your terminal and execute the following commands from the root directory of your local estimagic repository:

    $ conda env create -f environment.yml
$ conda activate estimagic
$ pre-commit install

    These commands install estimagic in editable mode and activate pre-commit hooks for linting and style formatting.

  3. 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.

  4. 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 paragraph 7 below) triggers estimagic’s Continuous Integration (CI) workflow, which runs the full pytest suite, pre-commit hooks, and other checks on a remote server.

    You can also run the test suite locally for debugging:

    $ pytest

    With pre-commit 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.

  1. Assuming you have updated the documentation, verify that it builds correctly. From the root directory of your local estimagic repo, navigate to the docs folder and set up the estimagic-docs environment:

    $ conda env create -f rtd_environment.yml
$ conda activate estimagic-docs

    Inside the docs folder, run:

    $ make html

    This command builds the HTML documentation, saving all files in the build/html directory. You can view the documentation with your preferred web browser by opening 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.

  2. Once all tests and pre-commit 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 estimagic repository and initiate a PR from there.

    Follow the steps outlined in the estimagic 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.

  3. 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.

  4. After your PR is approved, one of the main contributors will merge it into estimagic’s main branch.