|
| 1 | +# Overview |
| 2 | + |
| 3 | +Thank you for investing your time in contributing to our project! There are |
| 4 | +numbers of ways to contribute to the project and we appreciate all of them. If |
| 5 | +you like the project please give CppInterOp a star. |
| 6 | + |
| 7 | +Any contribution to open source makes a difference! |
| 8 | + |
| 9 | +## Are you new to open source, git or GitHub? |
| 10 | + |
| 11 | +To get an overview of the project, read the [README](README.md). Here are some |
| 12 | +resources to help you get started with open source contributions: |
| 13 | + |
| 14 | +- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) |
| 15 | +- [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) |
| 16 | +- [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) |
| 17 | +- [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) |
| 18 | + |
| 19 | +## Are you a contributor looking for a challenging summer project? |
| 20 | + |
| 21 | +Various opportunities such as information about google summer of code is |
| 22 | +generally published on the [Compiler Research Open Projects page](https://compiler-research.org/open_projects). |
| 23 | +If you have used CppInterOp and you have particular project proposal please reach out. |
| 24 | + |
| 25 | +## Ways to contribute |
| 26 | + |
| 27 | +### Submit a bug report |
| 28 | + |
| 29 | +If something does not seem right [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments) |
| 30 | +in [CppInterOps issue tracker](https://github.com/compiler-research/CppInterOp/issues). If a related issue doesn't exist, you can open a |
| 31 | +new issue using a relevant [issue form](https://github.com/compiler-research/CppInterOp/issues/new). |
| 32 | + |
| 33 | +### Good first issues |
| 34 | + |
| 35 | +Some issues have been marked as ["good first issues"](https://github.com/compiler-research/CppInterOp/labels/good%20first%20issue). |
| 36 | +These are intended to be a good place to start contributing. |
| 37 | + |
| 38 | +### Write documentation |
| 39 | + |
| 40 | +Documentation is critical for any open source project, especially for complex |
| 41 | +projects such as CppInterOp. We have our documentation in the repository which is then |
| 42 | +rendered in the [CppInterOp.readthedocs](https://cppinterop.readthedocs.io/en/latest/) website. |
| 43 | +Documentation modifications happen by proposing a pull request. |
| 44 | + |
| 45 | +## Creating a successfull pull request |
| 46 | + |
| 47 | +To propose a code modification we use the pull requests. Pull requests which |
| 48 | +review quickly and successfully share several common traits: |
| 49 | + |
| 50 | +- Sharp -- intends to fix a concrete problem. Usually the pull request addresses |
| 51 | + an already opened issue; |
| 52 | +- Atomic -- has one or more commits that can be reverted without any unwanted |
| 53 | + side effects or regressions, aside from what you’d expect based on its |
| 54 | + message. [More on atomic commits in git](https://www.aleksandrhovhannisyan.com/blog/atomic-git-commits/). |
| 55 | +- Descriptive -- has a good description in what is being solved. This |
| 56 | + information is usually published as part of the pull request description and |
| 57 | + as part of the commit message. Writing good commit messages are critical. More |
| 58 | + [here](https://github.blog/2022-06-30-write-better-commits-build-better-projects/) |
| 59 | + and [here](https://cbea.ms/git-commit/). If your pull request fixes an existing |
| 60 | + issue from the bug tracker make sure that the commit log and the pull request |
| 61 | + description mentions `Fixes: #<ISSUE_NUMBER>`. That will link both and will |
| 62 | + close the issue automatically upon merging. |
| 63 | +- Tested -- has a set of tests making sure that the issue will not resurface |
| 64 | + without a notice. Usually the codecov bots annotate the code paths that are |
| 65 | + not tested in the pull request after being run. |
| 66 | +- Documented -- has good amount of code comment. The test cases are also a good |
| 67 | + source of documentation. [Here](https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/) |
| 68 | + is a guideline about how write good code comments. [Here](https://stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encountered) |
| 69 | + are examples of what *not* to write as a code comment. |
| 70 | + |
| 71 | +### Developer Documentation |
| 72 | + |
| 73 | +We have documented several useful hints that usually help when addressing issues |
| 74 | +as they come during developement time in our [developer documentation](https://cppinterop.readthedocs.io/en/latest/InstallationAndUsage.html). |
0 commit comments