Skip to content

Commit

Permalink
Add debugging
Browse files Browse the repository at this point in the history
  • Loading branch information
@segsell
segsell committed Apr 20, 2024
1 parent 7b31ea0 commit cceb7d9
Showing 1 changed file with 57 additions and 71 deletions.
128 changes: 57 additions & 71 deletions docs/source/development/how-to.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,139 +2,125 @@

## 1. Intro

Contributions of all forms and sizes are welcome and highly appreciated! Anything from
updating the documentation, adding small extensions to implementing new features.
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 contribution is valued.

For substantial changes, please get in touch with us beforehand. This allows us to
discuss your ideas and guide the development process right from the start, which may
help clear up any misunderstandings and unecessary work. You can initiate a conversation
by posting an issue on GitHub or reaching out to [janosg](https://github.com/janosg) via
email.
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 familiarize yourself with the codebase, we recommed checking out our
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.

## 2. Before you start

Assuming you have settled on contributing to the project, we advise reviewing the
{ref}`style_guide` (see the next page) to ensure consistency with the project's coding
standards.
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.

We use Pull Requests (PR) to incorporate new features into the estimagic ecosystem.
Contributors work on a local estimagic copy where they can freely modify and extend the
codebase before opening a PR. With a PR you propose your changes to be merged into the
project's main branch. Regular contributors receive push access to unprotected branches,
which simplifies the contribution process.
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.

## 3. Step-by-step guide
Regular contributors gain push access to unprotected branches, which simplifies the
contribution process (see Notes below).

<!-- Here's a step-by-step guide for making contributions via PR, adhering to the estimagic
style guide: -->
## 3. Step-by-step guide

1. Fork the [estimagic repository](https://github.com/OpenSourceEconomics/estimagic/).
This will create a copy of the repository where you have write access.
This action creates a copy of the repository with write access for you.

```{note}
As a regular contributor, **clone** the [repository](https://github.com/OpenSourceEconomics/estimagic/) to your local machine and create a new local branch where you implement your changes. You can push your branch directly to the remote estimagic repository and open a PR from there.
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.
```

2. Clone the (forked) repository to your disc. You'll implement all changes and fixes
there.
2. Clone your forked repository to your disk. This is where you'll make all your
changes.

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

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

This automatically installs estimagic in editable mode and enables pre-commit hooks
for linting and stylistic error-checking.
These commands install estimagic in editable mode and activate pre-commit hooks for
linting and style formatting.

1. Implement your fix or feature. Use git to add, commit, and push your changes to the
remote repository. To learn more about git, how to stage and commit your work, have a
look at these
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).

1. Contributions are validated in two ways. First, we employ a comprehensive test suite
to check if new implementations are compatible with estimagic's existing codebase.
Second, we use
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 ensure contributions meet our quality standards and adhere to our stylistic
guidelines.
to maintain quality and adherence to our style guidelines. Opening a PR 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 (see paragraph 7 below).

Run the test suit with
You can also run the test suite locally for
[debugging](https://effective-programming-practices.vercel.app/debugging/pdbp/objectives_materials.html):

```bash
pytest
```

Look at the summary report and fix any errors that pop up.

With pre-commit installed, linters are executed before each commit. A commit is
rejected if any of the checks fails. Note that some linters fix the errors
automatically by modifying the code in-place. Restage the respective files.
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, check if it builds correctly. Go to the
root directory of your local estimagic repo and navigate to the `docs` folder. There,
you need to create the `estimagic-docs` environment and activate it
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
```

Inside the `docs` folder, type
Inside the `docs` folder, run:

```console
make html
```

which automatically builds the html documentation. All files are saved in the folder
`build\html`. You can open the html documentation with your browser of choice (e.g.
Google Chrome). E.g., use the following path to open the index page
This command builds the HTML documentation, saving all files in the `build/html`
directory. You can view the documentation using your preferred web browser by
navigating to:

```console
build/html/index.html
```

From the index page, you can navigate to any other section of the estimagic
documentation. Similarly, you can open specific pages directly, e.g.,

```console
$ build/html/explanations/optimization/why_optimization_is_hard.html
```

1. Once all tests and pre-commit hooks pass locally, push your changes to the forked
estimagic repository, and create a pull request through the GitHub interface: Go to
the Github repository of your fork. A banner will be displayed asking you whether you
would like to create a pull request. Click on the link.
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.

```{note}
Regular contributors with push access can push their local branch to the remote estimagic repository directly and start a PR from there.
Regular contributors with push access can directly push their local branch to the remote estimagic repository and initiate a PR from there.
```

Follow the instructions of the estimagic
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 you address, and your proposed solution.
to describe your contribution, the problem it addresses, and your proposed solution.

Opening a PR starts a complete run of the test suite on a
[Continuous Integration (CI)](https://docs.github.com/en/actions/automating-builds-and-tests/about-continuous-integration)
server. Along with `pytest`, the CI workflow includes linters, code coverage checks,
doctests, and builds the html documentation. The status of the CI run is shown on
your PR page. If any errors pop up, make the corresponding modifications to your code
and reiterate until all CI tests have passed 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. Make sure all CI tests pass
before you request a review. If the reviewer(s) have any remarks or suggestions,
address them, and commit your modifications.
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. Once you're PR is approved, one of the main contributors will merge it into
1. After your PR is approved, one of the main contributors will merge it into
estimagic's main branch.

0 comments on commit cceb7d9

Please sign in to comment.