|
| 1 | +# Guidelines for contributing |
| 2 | + |
| 3 | +## General workflow |
| 4 | + |
| 5 | +We are using [Git][git], [GitHub][github] and [Git Flow][git-flow]. |
| 6 | + |
| 7 | +> **Note:** If you are a **beginner** and do not have a lot of experience with |
| 8 | +> this sort of workflow, please do not feel overwhelmed. We will guide you |
| 9 | +> through the process until you feel comfortable using it. And do not worry |
| 10 | +> about mistakes either - everybody does them. Often! Our project layout makes |
| 11 | +> it very very hard for anyone to cause irreversible harm, so relax, try things |
| 12 | +> out, take your time and enjoy the work! :) |
| 13 | +
|
| 14 | +We would kindly ask you to abide by our [Code of Conduct][coc] in all |
| 15 | +interactions with the community when contributing to this project, regardless |
| 16 | +of the type of contribution. We will not accept any offensive or demeaning |
| 17 | +behavior towards others and will take any necessary steps to ensure that |
| 18 | +everyone is treated with respect and dignity. |
| 19 | + |
| 20 | +## Issue tracker |
| 21 | + |
| 22 | +Please use each project's GitHub [issue tracker][issue-tracker] to: |
| 23 | + |
| 24 | +- find issues to work on |
| 25 | +- report bugs |
| 26 | +- propose features |
| 27 | +- discuss future directions |
| 28 | + |
| 29 | +## Submitting issues |
| 30 | + |
| 31 | +Please choose a template when submitting an issue: choose the [**bug report** |
| 32 | +template][bug-report] only when reporting bugs; for all other issues, |
| 33 | +choose the [**feature request** template][bug-report]. Please follow the |
| 34 | +instructions in the templates. |
| 35 | + |
| 36 | +You do not need to worry about adding labels or milestones for an issue, the |
| 37 | +project maintainers will do that for you. However, it is important that all |
| 38 | +issues are written concisely, yet with enough detail and with proper |
| 39 | +references (links, screenshots, etc.) to allow other contributors to start |
| 40 | +working on them. For bug reports, it is essential that they include all |
| 41 | +information required to reproduce the bug. |
| 42 | + |
| 43 | +Please **do not** use the issue tracker to ask usage questions, installation |
| 44 | +problems etc., unless they appear to be bugs. For these issues, please use |
| 45 | +the [communication channels](#communication) outlined below. |
| 46 | + |
| 47 | +## Communication |
| 48 | + |
| 49 | +Send us an [email][contact] if you want to reach out to us |
| 50 | +work on) |
| 51 | + |
| 52 | +## Code style and testing |
| 53 | + |
| 54 | +To make it easier for everyone to maintain, read and contribute to the code, |
| 55 | +as well as to ensure that the code base is robust and of high quality, we |
| 56 | +would kindly ask you to stick to the following guidelines for code style and |
| 57 | +testing. |
| 58 | + |
| 59 | +- Please use a recent version of [Python 3][py] (3.7.4+) |
| 60 | +- Please try to conform to the used code, docstring and commenting style within |
| 61 | + a project to maintain consistency |
| 62 | +- Please use [type hints][py-typing] for all function/method signatures |
| 63 | + (exception: tests) |
| 64 | +- Please use the following linters (see configuration files in repository root |
| 65 | + directory, e.g., `setup.cfg`, for settings): |
| 66 | + - [`flake8`][py-flake8] |
| 67 | + - [`pylint`][py-pylint] (use available [configuration][py-pylint-conf]) |
| 68 | + - [`mypy`][py-mypy] OR [`pyright`][py-pyright] to help with type hints |
| 69 | +- Please use the following test suites: |
| 70 | + - [`pytest`][py-pytest] |
| 71 | + - [`coverage`][py-coverage] |
| 72 | + |
| 73 | +## Commit messages |
| 74 | + |
| 75 | +In an effort to increase consistency, simplify maintenance and enable automated |
| 76 | +change logs, we would like to kindly ask you to write _semantic commit |
| 77 | +messages_, as described in the [Conventional Commits |
| 78 | +specification][conv-commits]. |
| 79 | + |
| 80 | +The general structure of _Conventional Commits_ is as follows: |
| 81 | + |
| 82 | +```console |
| 83 | +<type>[optional scope]: <description> |
| 84 | + |
| 85 | +[optional body] |
| 86 | + |
| 87 | +[optional footer] |
| 88 | +``` |
| 89 | + |
| 90 | +Depending on the changes, please use one of the following **type** prefixes: |
| 91 | + |
| 92 | +| Type | Description | |
| 93 | +| --- | --- | |
| 94 | +| build | The build type (formerly known as chore) is used to identify development changes related to the build system (involving scripts, configurations or tools) and package dependencies. | |
| 95 | +| ci | The ci type is used to identify development changes related to the continuous integration and deployment system - involving scripts, configurations or tools. | |
| 96 | +| docs | The docs type is used to identify documentation changes related to the project - whether intended externally for the end users (in case of a library) or internally for the developers. | |
| 97 | +| feat | The feat type is used to identify production changes related to new backward-compatible abilities or functionality. | |
| 98 | +| fix | The fix type is used to identify production changes related to backward-compatible bug fixes. | |
| 99 | +| perf | The perf type is used to identify production changes related to backward-compatible performance improvements. | |
| 100 | +| refactor | The refactor type is used to identify development changes related to modifying the codebase, which neither adds a feature nor fixes a bug - such as removing redundant code, simplifying the code, renaming variables, etc. | |
| 101 | +| revert | For commits that revert one or more previous commits. | |
| 102 | +| style | The style type is used to identify development changes related to styling the codebase, regardless of the meaning - such as indentations, semi-colons, quotes, trailing commas and so on. | |
| 103 | +| test | The test type is used to identify development changes related to tests - such as refactoring existing tests or adding new tests. | |
| 104 | + |
| 105 | +In order to ensure that the format of your commit messages adheres to the |
| 106 | +Conventional Commits specification and the defined type vocabulary, you can |
| 107 | +use the [dedicated linter][conv-commits-lint]. More information about |
| 108 | +_Conventional Commits_ can also be found in this [blog |
| 109 | +post][conv-commits-blog]. |
| 110 | + |
| 111 | +## Merging your code |
| 112 | + |
| 113 | +Here is a check list that you can follow to make sure that code merges |
| 114 | +happen smoothly: |
| 115 | + |
| 116 | +1. [Open an issue](#submitting-issues) _first_ to give other contributors a |
| 117 | + chance to discuss the proposed changes (alternatively: assign yourself |
| 118 | + to one of the existing issues) |
| 119 | +2. Clone the repository, create a feature branch off of the default branch |
| 120 | + (never commit changes to protected branches directly) and implement your |
| 121 | + code changes |
| 122 | +3. If applicable, update relevant sections of the [documentation][docs] |
| 123 | +4. Add or update tests; untested code will not be merged; refer to the |
| 124 | + [guidelines](#code-style-and-testing) above for details |
| 125 | +5. Ensure that your coding style is in line with the |
| 126 | + [guidelines](#code-style-and-testing) described above |
| 127 | +6. Ensure that all tests and linter checks configured in the [Travis |
| 128 | + CI][travis-docs] [continuous integration][ci-cd] (CI) pipeline pass without |
| 129 | + issues |
| 130 | +7. If necessary, clean up excessive commits with `git rebase`; cherry-pick and |
| 131 | + merge commits as you see fit; use concise and descriptive commit messages |
| 132 | +8. Push your clean, tested and documented feature branch to the remote; make |
| 133 | + sure the [Travis CI][travis-docs] [CI][ci-cd] pipeline passes |
| 134 | +9. Issue a pull request against the default branch; follow the instructions in |
| 135 | + the [template][pull-request]; importantly, describe your changes in |
| 136 | + detail, yet with concise language, and do not forget to indicate which |
| 137 | + issue(s) the code changes resolve or refer to; assign a project maintainer |
| 138 | + to review your changes |
| 139 | + |
| 140 | +## Becoming a co-maintainer |
| 141 | + |
| 142 | +If you are as interested in the project as we are and have contributed some |
| 143 | +code, suggested some features or bug reports and have taken part in |
| 144 | +discussions on where to go with the project, we will very likely to have you |
| 145 | +on board as a co-maintainer. If you are intersted in that, please let us |
| 146 | +know. You can reach us by [email][contact]. |
| 147 | + |
| 148 | +[bug-report]: .github/ISSUE_TEMPLATE/bug_report.mdrequest.md |
| 149 | +[ci-cd]: <https://en.wikipedia.org/wiki/Continuous_integration> |
| 150 | +[coc]: CODE_OF_CONDUCT.md |
| 151 | +[contact]: <zavolab-biozentrum@unibas.ch> |
| 152 | +[conv-commits]: <https://www.conventionalcommits.org/en/v1.0.0-beta.2/#specification> |
| 153 | +[conv-commits-blog]: <https://nitayneeman.com/posts/understanding-semantic-commit-messages-using-git-and-angular/> |
| 154 | +[conv-commits-lint]: <https://github.com/conventional-changelog/commitlint> |
| 155 | +[docs]: README.md |
| 156 | +[git]: <https://git-scm.com/> |
| 157 | +[git-flow]: <https://nvie.com/posts/a-successful-git-branching-model/> |
| 158 | +[github]: <https://github.com> |
| 159 | +[issue-tracker]: <https://github.com/zavolanlab/zarp/issues> |
| 160 | +[pull-request]: PULL_REQUEST_TEMPLATE.md |
| 161 | +[py]: <https://www.python.org/> |
| 162 | +[py-flake8]: <https://gitlab.com/pycqa/flake8> |
| 163 | +[py-mypy]: <http://mypy-lang.org/> |
| 164 | +[py-pylint]: <https://www.pylint.org/> |
| 165 | +[py-pylint-conf]: pylint.cfg |
| 166 | +[py-pyright]: <https://github.com/microsoft/pyright> |
| 167 | +[py-pytest]: <https://docs.pytest.org/en/latest/> |
| 168 | +[py-coverage]: <https://pypi.org/project/coverage/> |
| 169 | +[py-typing]: <https://docs.python.org/3/library/typing.html> |
| 170 | +[travis-docs]: <https://docs.travis-ci.com/> |
0 commit comments