|
1 | | -# Guidelines for contributing |
| 1 | +# Contributing |
2 | 2 |
|
3 | | -## Issue tracker |
| 3 | +## Reporting bugs 🐛 |
4 | 4 |
|
5 | | -Please use each project's GitHub [issue tracker][res-issue-tracker] to: |
| 5 | +Before reporting a bug, try to search for a similar problem in the *Issues* section on GitHub. Clear the search bar to include closed issues in the search and type your phrase. |
6 | 6 |
|
7 | | -- find issues to work on |
8 | | -- report bugs |
9 | | -- propose features |
10 | | -- discuss future directions |
| 7 | +If you have not found a relevant issue, you can report the bug in the *Issues* section. When you click on *New issue*, various templates will be displayed — please pick *Bug Report*. Carefully fill out the template and submit the issue. |
11 | 8 |
|
12 | | -## Submitting issues |
| 9 | +## Requesting features 💡 |
13 | 10 |
|
14 | | -Please choose a template when submitting an issue: choose the [Bug report |
15 | | -template][res-bug-report] only when reporting bugs; for all other issues, |
16 | | -choose the [Feature request template][res-feature-request]. Please follow the |
17 | | -instructions in the template. |
| 11 | +If you have an idea for improvement, you can submit your proposal in the *Issues* section on GitHub. When you click on *New issue*, various templates will be displayed — please pick *Feature Request*. Carefully fill out the template and submit the issue. |
18 | 12 |
|
19 | | -You do not need to worry about adding labels or milestones for an issue, the |
20 | | -project maintainers will do that for you. However, it is important that all |
21 | | -issues are written concisely, yet with enough detail and with proper |
22 | | -references (links, screenshots, etc.) to allow other contributors to start |
23 | | -working on them. For bug reports, it is essential that they include |
24 | | -reproducible examples. |
| 13 | +## Pull requests ⤴️ |
25 | 14 |
|
26 | | -Please **do not** use the issue tracker to ask usage questions, installation |
27 | | -problems etc., unless they appear to be bugs. |
| 15 | +**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request) |
28 | 16 |
|
29 | | -## Code style & testing |
| 17 | +### Local development environment setup |
| 18 | + |
| 19 | +In order to develop/test the library one should have the following dependencies |
| 20 | +installed: |
| 21 | +* _g++/clang++_ |
| 22 | +* _cpplint_ |
| 23 | +* _doxygen_ |
| 24 | +* _make_ |
| 25 | +* _mpfr_ |
| 26 | +* _pre-commit_ |
| 27 | +* _valgrind_ |
| 28 | + |
| 29 | +For Ubuntu we recommend `apt` package manager, for macOS - `brew`. |
| 30 | + |
| 31 | +Following cloning the repository the first action one should take is to |
| 32 | +install pre-commit hooks for `git` with the following command: |
| 33 | +```bash |
| 34 | +pre-commit install |
| 35 | +``` |
| 36 | +Dev commands have been encapsulated in the _Makefile_, see: `make help` for more info. |
| 37 | + |
| 38 | +An alternative approach to set up the environment involves building |
| 39 | +an isolated environment, just for this project: |
| 40 | + |
| 41 | +1. Install Conda (package management system and environment management). You can find the installation instructions in |
| 42 | + [Anaconda page](https://www.anaconda.com/) or in [Miniconda page](https://docs.conda.io/en/latest/miniconda.html). |
| 43 | +2. Setup a Conda environment to install all needed dependencies: |
| 44 | + ```bash |
| 45 | + conda env create |
| 46 | + ``` |
| 47 | +3. In order to activate newly created Conda environment type: |
| 48 | + |
| 49 | + ```bash |
| 50 | + conda activate hypercomplex-dev |
| 51 | + ``` |
| 52 | + |
| 53 | + If you have no experience with Conda environments, read about them |
| 54 | + [under this address](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html). |
| 55 | + |
| 56 | +PS. Remember that if you work in a conda environment and use internal compilers |
| 57 | +it may be necessary to provide additional paths to the headers and for the linker |
| 58 | +at the compilation time (flags: `-I` and `-L`), thus you may be required to |
| 59 | +adjust the commands in the _Makefile_(!) Please see the "conda" CI jobs, |
| 60 | +they are related to building a conda package but this note applies to these tests too. |
| 61 | + |
| 62 | +### local Docker container |
| 63 | + |
| 64 | +We have additionally prepared a development/execution Docker image which one may use in order to |
| 65 | +work on our project in a fully encapsulated environment (that is: a container). |
| 66 | +Assuming the Docker Engine is running locally please build the image with: |
| 67 | +``` |
| 68 | +docker build -t hypercomplex:latest -f Dockerfile-dev . |
| 69 | +``` |
| 70 | +Once the process is finished start & enter the container with: |
| 71 | +``` |
| 72 | +docker run --name hypercomplex -e HOSTUID=`id -u $USER` -p 8888:8888 -v {HOST_PATH_TO_HYPERCOMPLEX}:/hypercomplex -it fuzzyreg:latest |
| 73 | +``` |
| 74 | +Watch out! Due to Docker's specifics they need to be executed as `root` user; |
| 75 | +[alternatively, see here](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). |
| 76 | + |
| 77 | +Recall that all data generated inside the container (with the exception of the mounted volume) are **not** persistent. |
| 78 | +If you'd like your data don't perish into oblivion after you stop the container |
| 79 | +check out [Docker documentation on storage mechanisms](https://docs.docker.com/storage/). |
| 80 | + |
| 81 | +### Ephemeral development environment |
| 82 | + |
| 83 | +(╯°□°)╯︵ ┻━┻ |
| 84 | +If that above is you, feeling like flipping a table just by the sheer looks of all the instructions above, do not despair! You still can contribute to our codebase from the cloud! We set up an ephemeral [Gitpod](https://www.gitpod.io) environment for all the developers who prefer coding from a remote server. |
| 85 | + |
| 86 | +Just click on this cool button below: |
| 87 | +[](https://gitpod.io/#https://github.com/AngryMaciek/hypercomplex) |
| 88 | + |
| 89 | +See more information on how to start up a _Gitpod_ environment dedicated to a specific remote branch [here](https://www.gitpod.io/docs/introduction/learn-gitpod/context-url#branch-and-commit-contexts), specific issue [here](https://www.gitpod.io/docs/introduction/learn-gitpod/context-url#issue-context) and a specific pull request [here](https://www.gitpod.io/docs/introduction/learn-gitpod/context-url#pullmerge-request-context). |
| 90 | + |
| 91 | +However, please remember that such luxury is limitted: |
| 92 | + |
| 93 | +> Gitpod offers a free plan for new users which includes 50 hours of standard workspace usage. |
| 94 | +> If you need more hours, you can upgrade to one of the paid plans in your personal settings. |
| 95 | +
|
| 96 | +### Branch naming convention |
| 97 | + |
| 98 | +You can read about git branching [under this address](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging). The branch names should follow the convention specified below: |
| 99 | + |
| 100 | +``` |
| 101 | +<type>/<issue id>/<short description> |
| 102 | +``` |
| 103 | + |
| 104 | +where |
| 105 | + |
| 106 | +- **type** is one of the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)' types, i.e. `feat`, `ci`, `docs`, `fix`, `refactor`, `test`, `chore`, etc. |
| 107 | +- **issue id** is the id of the issue which will be fixed by this PR. |
| 108 | +- **short description** is ~25 characters long at max and is hyphenated. |
| 109 | + |
| 110 | +Examples: |
| 111 | + |
| 112 | +``` |
| 113 | +chore/6/gitignore |
| 114 | +ci/20/testing-and-code-coverage |
| 115 | +ci/21/flake8-action |
| 116 | +ci/46/docstring-linting |
| 117 | +docs/22/contributing-instructions |
| 118 | +feat/3/license |
| 119 | +feat/4/github-templates |
| 120 | +feat/40/version-flag |
| 121 | +feat/7/code-of-conduct |
| 122 | +refactor/8/initial-project-structure |
| 123 | +``` |
| 124 | + |
| 125 | +### Code style & testing |
30 | 126 |
|
31 | 127 | To make it easier for everyone to maintain, read and contribute to the code, |
32 | 128 | as well as to ensure that the code base is robust and of high quality, we |
33 | 129 | would kindly ask you to stick to the guidelines for code style and |
34 | 130 | testing. GitHub Actions mechanism of Continous Integration tests the code |
35 | | -style with [cpplint] and performs unit tests with the [Catch2] framework |
| 131 | +style with _cpplint_ and performs unit tests with the _Catch2_ framework |
36 | 132 | (measuring code coverage alongside). |
37 | 133 | Also, please try to conform to the used code, docstring and commenting style within |
38 | 134 | a project to maintain consistency. |
39 | 135 |
|
40 | | -## Merging your code |
41 | | - |
42 | | -Here is a check list that you can follow to make sure that code merges |
43 | | -happen smoothly: |
44 | | - |
45 | | -1. [Open an issue](#submitting-issues) first to give other contributors a |
46 | | - chance to discuss the proposed changes (alternatively: assign yourself |
47 | | - to one of the existing issues) |
48 | | -2. Fork the repository, clone it & create a feature branch off of the default branch |
49 | | - (never commit changes to protected branches directly) and implement your |
50 | | - code changes |
51 | | -3. If applicable, update relevant sections of the documentation |
52 | | -4. Add or update tests; untested code will not be merged; refer to the |
53 | | - [guidelines](#code-style--testing) above for details |
54 | | -5. Ensure that your coding style is in line with the |
55 | | - [guidelines](#code-style--testing) described above |
56 | | -6. Ensure that all tests and linter checks configured in the CI pipeline pass without issues |
57 | | -7. If necessary, clean up excessive commits with `git rebase`; cherry-pick and |
58 | | - merge commits as you see fit; use concise and descriptive commit messages |
59 | | -8. Push your clean, tested and documented feature branch to the remote; make |
60 | | - sure the CI pipeline passes |
61 | | -9. Issue a pull request from your fork against the default branch in the original repository; follow the instructions in |
62 | | - the [template][res-pull-request]; importantly, describe your changes in |
63 | | - detail, yet with concise language, and do not forget to indicate which |
64 | | - issue(s) the code changes resolve or refer to; assign a project maintainer |
65 | | - to review your changes |
66 | | - |
67 | | - |
68 | | -[res-issue-tracker]: <https://github.com/AngryMaciek/hypercomplex/issues> |
69 | | -[res-bug-report]: .github/ISSUE_TEMPLATE/bug_report.md |
70 | | -[res-feature-request]: .github/ISSUE_TEMPLATE/feature_request.md |
71 | | -[cpplint]: <https://github.com/cpplint/cpplint> |
72 | | -[Catch2]: <https://github.com/catchorg/Catch2> |
73 | | -[res-pull-request]: PULL_REQUEST_TEMPLATE.md |
| 136 | +### Merging the pull request |
| 137 | + |
| 138 | +A pull request can only be merged after it completed all of the checks performed by CI. After a manual review by one of the maintainers, it can be merged into `master`. The merge commit should follow the rules outlined in [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). |
0 commit comments