## Contributing to mockturtle

:+1::tada: First off, thanks for your interest in contributing! :tada::+1:

### How to make a pull request

Contributing of code to mockturtle -- either fixing issues or adding new features -- should be made via pull requests (PRs). To do so:
1. Make a *fork* of mockturtle into your GitHub account.
2. It is a good idea to keep the `master` (or `main`) branch of your fork up-to-date with mainstream mockturtle. Thus, it is recommended to *create a branch* before making changes.
3. Edit or add new code, [compile](https://mockturtle.readthedocs.io/en/latest/getting_started.html#using-mockturtle-as-a-stand-alone-tool) and [test](https://mockturtle.readthedocs.io/en/latest/getting_started.html#building-tests) it. *Commit* to the branch you've created.
4. When everything is ready (go through the check list below!), come back to mockturtle's GitHub page and go to [Pull requests](https://github.com/lsils/mockturtle/pulls). Click on "New pull request". Choose the correct branch in your fork and make sure the base is `lsils/mockturtle/master`.
5. Give the pull request a comprehensive title and sufficient descriptions. Then click on "Create pull request".

### Pull request check list

Please go through this self-check list before/during making a pull request.

#### Before making a PR

- [ ] **Unit testing:** If you add new functionalities (new data structures, new utilities, new algorithms, etc.), please add unit tests in the `test/` folder to test your code thoroughly.
- [ ] **File header and documentation comments:** When adding a new file, please copy-paste the file header from another file in mockturtle (comments including copyright information, file name, brief description, and authors) and edit the information accordingly. When adding new functions or classes, add a comment before the code to document its purpose and usage. Please use the same syntax as existing ones, e.g. like [here](https://github.com/lsils/mockturtle/blob/c3dbefccec3f9b120b5341e467caf9ecddfce54b/include/mockturtle/generators/arithmetic.hpp#L51), such that `doxygen` can recognize them.
- [ ] **Documentation:** If you add new functionalities, please write sufficient documentation to let people know how to use your code. Besides writing comments in the code, you also need to add some lines in the corresponding `.rst` file or even adding a new `.rst` file (when doing so, remember to add this file in the appropriate `index_*.rst` file). Try to compile and preview the edited documentation webpage by running `make html` in the `docs/` folder.
- [ ] **Coding style:** Please run `clang-format -i <path_to_files_you_edited>` to make sure that the code you contribute adheres to the coding style of the project.
- [ ] **Back-porting changes to other projects:** If you make changes to any project in the `lib/` folder that belongs to the [EPFL logic synthesis libraries](https://github.com/lsils/lstools-showcase), please also make a pull request to the corresponding project repository.
- [ ] **Final check:** It's a good idea to check the "files changed" page (which you should see during submitting the PR, or by clicking on "compare branch"). Make sure everything is intended, and there is no extra debugging code or files generated by your editor etc.

#### After submitting a PR

- [ ] **Change log:** Remember to record your contributions in the change log by adding an item in [changelog.rst](https://github.com/lsils/mockturtle/blob/master/docs/changelog.rst). (You will refer to the PR number, which is easier to look up *after* submitting the PR.)
- [ ] **CI tests:** Make sure that the CI tests pass (i.e., having a green check mark). If this is your first time contributing to mockturtle, you might need to wait for a maintainer to manually approve and run the CI tests.
- [ ] **Test coverage:** If the CI tests pass, after a while, the code coverage bot should leave a comment in your PR, showing the changes on the test coverage. It would be nice to have it slightly increased, or at least not dropping too much. Try adding more tests to increase coverage.
- [ ] **Code quality:** After the CIs are finished, take a look at the "Code scanning results" among the checks. It may alert you about potential problems in your code.
- [ ] It will be confusing to the maintainers whether your PR is ready for review if you keep adding more commits after submitting the PR. If more changes are needed, you may temporarily close the PR or turn it into a draft. When it's ready for review, add a comment to let us know.

