diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2d155d1aa..dc66fe1d0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -52,12 +52,12 @@ repos: - id: check-docstring-first exclude: src/estimagic/optimization/algo_options.py - repo: https://github.com/adrienverge/yamllint.git - rev: v1.33.0 + rev: v1.35.1 hooks: - id: yamllint exclude: tests/optimization/fixtures - repo: https://github.com/psf/black - rev: 24.1.1 + rev: 24.3.0 hooks: - id: black language_version: python3.10 @@ -79,11 +79,11 @@ repos: - --blank exclude: src/estimagic/optimization/algo_options.py - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.2.0 + rev: v0.3.5 hooks: - id: ruff - repo: https://github.com/nbQA-dev/nbQA - rev: 1.7.1 + rev: 1.8.5 hooks: - id: nbqa-black - id: nbqa-ruff diff --git a/docs/source/development/how-to.md b/docs/source/development/how-to.md index 2c7522f41..9bf2d3866 100644 --- a/docs/source/development/how-to.md +++ b/docs/source/development/how-to.md @@ -1,75 +1,123 @@ # How to contribute -Contributions are always welcome. Everything ranging from small extensions of the -documentation to implementing new features is appreciated. Of course, the bigger the -change the more it is necessary to reach out to us in advance for an discussion. You can -post an issue or contact [janosg](https://github.com/janosg) via email. +## 1. Intro -To get acquainted with the code base, you can also check out our +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](https://github.com/janosg). + +To get familiar with the codebase, we recommend checking out our [issue tracker](https://github.com/OpenSourceEconomics/estimagic/issues) for some immediate and clearly defined tasks. -1. Assuming you have settled on contributing a small fix to the project, please read the - {ref}`style_guide` on the next page before you continue. +## 2. Before you start -1. Next, fork the [repository](https://github.com/OpenSourceEconomics/estimagic/). This - will create a copy of the repository where you have write access. Your fix will be - implemented in your copy. After that, you will start a pull request (PR) which means - a proposal to merge your changes into the project. If you plan to become a regular - contributor we can give you push access to unprotected branches, which makes the - process more convenient for you. +Once you've decided to contribute, please review the {ref}`style_guide` (see the next +page) to ensure your work aligns with the project's coding standards. -1. Clone the repository to your disk. Set up the project environment with conda and the - and install your local version of estimagic in editable mode. The commands for this - are (in a terminal in the root of your local estimagic repo): +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. - `conda env create -f environment.yml` +Regular contributors gain push access to unprotected branches, which simplifies the +contribution process (see Notes below). - `conda activate estimagic` +## 3. Step-by-step guide - `pip install -e .` +1. Fork the [estimagic repository](https://github.com/OpenSourceEconomics/estimagic/). + This action creates a copy of the repository with write access for you. -1. Implement the fix or new feature. +```{note} +For regular contributors: **Clone** the [repository](https://github.com/OpenSourceEconomics/estimagic/) 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. We validate contributions in three ways. First, we have a test suite to check the - implementation of respy. Second, we correct for stylistic errors in code and - documentation using linters. Third, we test whether the documentation builds - successfully. +2. Clone your forked repository to your disk. This is where you'll make all your + changes. - You can run all checks with `tox` by running +1. Open your terminal and execute the following commands from the root directory of your + local estimagic repository: - ```bash - $ tox + ```console + $ conda env create -f environment.yml + $ conda activate estimagic + $ pre-commit install ``` - This will run the complete test suite. To run only a subset of the suite you can use - the environments, `pytest`, `linting` and `sphinx`, with the `-e` flag of tox. + These commands install estimagic in editable mode and activate pre-commit hooks for + linting and style formatting. - Correct any errors displayed in the terminal. +1. 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](https://effective-programming-practices.vercel.app/git/staging/objectives_materials.html). - To correct stylistic errors, you can also install the linters as a pre-commit with +1. 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](https://effective-programming-practices.vercel.app/git/pre_commits/objectives_materials.html) + to maintain quality and adherence to our style guidelines. Opening a PR (see + paragraph 7 below) triggers estimagic's + [Continuous Integration (CI)](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration) + workflow, which runs the full `pytest` suite, pre-commit hooks, and other checks on a + remote server. - ```bash - $ pre-commit install + You can also run the test suite locally for + [debugging](https://effective-programming-practices.vercel.app/debugging/pdbp/objectives_materials.html): + + ```console + $ 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. +``` + +6. 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: + + ```console + $ conda env create -f rtd_environment.yml + $ conda activate estimagic-docs ``` - Then, all the linters are executed before each commit and the commit is aborted if - one of the check fails. You can also manually run the linters with + Inside the `docs` folder, run: + + ```console + $ 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. + +1. 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. - ```bash - $ pre-commit run -a + ```{note} + Regular contributors with push access can directly push their local branch to the remote estimagic repository and initiate a PR from there. ``` -5) If the tests pass, push your changes to your repository. Go to the Github page of - your fork. A banner will be displayed asking you whether you would like to create a - PR. Follow the link and the instructions of the PR template. Fill out the PR form to - inform everyone else on what you are trying to accomplish and how you did it. + Follow the steps outlined in the estimagic + [PR template](https://github.com/OpenSourceEconomics/estimagic/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) + to describe your contribution, the problem it addresses, and your proposed solution. - The PR also starts a complete run of the test suite on a continuous integration - server. The status of the tests is shown in the PR. Reiterate on your changes until - the tests pass on the remote machine. + 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. -1) Ask one of the main contributors to review your changes. Include their remarks in - your changes. +1. 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. -1) The final PR will be merged by one of the main contributors. +1. After your PR is approved, one of the main contributors will merge it into + estimagic's main branch.