|
| 1 | +Contributing |
| 2 | +================ |
| 3 | + |
| 4 | +**Thank you for your interest in Zelt! |
| 5 | +Your contributions are highly welcome.** |
| 6 | + |
| 7 | +There are multiple ways to get involved: |
| 8 | + |
| 9 | +.. contents:: |
| 10 | + :local: |
| 11 | + |
| 12 | +Make sure you always follow our simple `code of conduct`_. |
| 13 | +If you need help, please reach out to us by `opening an issue`_. |
| 14 | + |
| 15 | +.. _code of conduct: https://github.com/zalando-incubator/zelt/blob/master/CODE_OF_CONDUCT.md |
| 16 | +.. _opening an issue: https://github.com/zalando-incubator/zelt/issues/new/choose |
| 17 | + |
| 18 | +Report a bug |
| 19 | +------------ |
| 20 | + |
| 21 | +Reporting bugs is one of the best ways to contribute. |
| 22 | +Before creating a bug report, please check that an issue_ reporting the same |
| 23 | +problem **does not already exist**. |
| 24 | +If there is such an issue, show your interest with an emoji reaction on the |
| 25 | +issue's description, and add the results of your investigation (if any) in a |
| 26 | +comment. |
| 27 | + |
| 28 | +.. _issue: https://github.com/zalando-incubator/zelt/issues |
| 29 | + |
| 30 | +To report a **new bug**, `open a bug report`_ describing the problem. |
| 31 | + |
| 32 | +.. _open a bug report: https://github.com/zalando-incubator/zelt/issues |
| 33 | + /new?labels=bug&template=bug_report.md |
| 34 | + |
| 35 | +If you want to provide a fix along with your bug report, that's great! |
| 36 | +In that case, please send us a **pull request** as described below in the |
| 37 | +:ref:`contribute-code` section. |
| 38 | + |
| 39 | +Suggest a feature |
| 40 | +----------------- |
| 41 | + |
| 42 | +To propose a new feature for Zelt, `open a feature request`_ and |
| 43 | +summarize the desired functionality and the problem you're trying to solve. |
| 44 | + |
| 45 | +.. _open a feature request: https://github.com/zalando-incubator/zelt |
| 46 | + /issues/new?template=feature_request.md&labels=enhancement |
| 47 | + |
| 48 | +.. _contribute-code: |
| 49 | + |
| 50 | +Contribute code |
| 51 | +--------------- |
| 52 | + |
| 53 | +.. _set-up-dev: |
| 54 | + |
| 55 | +Set up a dev environment |
| 56 | +'''''''''''''''''''''''' |
| 57 | + |
| 58 | +The only required dependency for local deployment is Poetry_. |
| 59 | + |
| 60 | +.. _Poetry: https://poetry.eustace.io/docs/#installation |
| 61 | + |
| 62 | +Once you have Poetry, you can simply call ``make install`` to install all |
| 63 | +necessary dependencies. |
| 64 | +This mimics what happens in our continuous integration pipeline, so you won't |
| 65 | +get surprised. |
| 66 | + |
| 67 | +.. _project-conventions: |
| 68 | + |
| 69 | +Conventions |
| 70 | +''''''''''' |
| 71 | + |
| 72 | +- All source code is formatted using black_. |
| 73 | + |
| 74 | +- All non-private functions are reasonably covered by unit tests runnable |
| 75 | + with Pytest_ (via ``make test``). |
| 76 | + |
| 77 | +- All user-facing APIs are clearly documented using Sphinx_ in docstrings |
| 78 | + (for developers) and in reST files in the :file:`docs/` directory (for |
| 79 | + users). |
| 80 | + See :ref:`documentation` for details. |
| 81 | + |
| 82 | +- All user-facing changes are reported in :ref:`changelog`, along with a |
| 83 | + reference to the relevant pull request or issue identifiers. |
| 84 | + |
| 85 | +.. _black: https://black.readthedocs.io/ |
| 86 | +.. _Pytest: https://docs.pytest.org/ |
| 87 | +.. _Sphinx: https://www.sphinx-doc.org/ |
| 88 | + |
| 89 | +Suggested workflow |
| 90 | +'''''''''''''''''' |
| 91 | + |
| 92 | +.. highlight:: bash |
| 93 | + |
| 94 | +1. Check the list of `open issues`_. |
| 95 | + Either **assign yourself to an existing issue**, or `create a new one`_ that |
| 96 | + you would like to work on. |
| 97 | + Describe the problem you're trying to solve, and your ideas for solving it. |
| 98 | + |
| 99 | + It is always best to **discuss your plans** beforehand: it ensures that your |
| 100 | + contribution is in line with the goals of the project. |
| 101 | + |
| 102 | +.. _open issues: https://github.com/zalando-incubator/zelt/issues |
| 103 | +.. _create a new one: https://github.com/zalando-incubator/zelt/issues/new/choose |
| 104 | + |
| 105 | +2. **Fork** the `repository on GitHub`_ and clone your fork:: |
| 106 | + |
| 107 | + $ git clone https://github.com/my-pseudo/zelt.git |
| 108 | + |
| 109 | +.. _repository on GitHub: https://github.com/zalando-incubator/zelt |
| 110 | + |
| 111 | +3. Create a **feature branch**, for example ``my-feature``, starting from the |
| 112 | + ``master`` branch:: |
| 113 | + |
| 114 | + $ git checkout -b my-feature |
| 115 | + |
| 116 | + Push that branch on your fork:: |
| 117 | + |
| 118 | + $ git push -u origin my-feature |
| 119 | + |
| 120 | +4. Open a `new pull request`_ in `draft mode`_, and explain what you are doing: |
| 121 | + which issue_ are you solving and how? |
| 122 | + |
| 123 | + Using the **draft mode** prevents from immediately sending a request for |
| 124 | + code review to all maintainers, so it's useful when you don't yet have all |
| 125 | + your code ready. |
| 126 | + |
| 127 | +.. _new pull request: https://github.com/zalando-incubator/zelt/compare |
| 128 | +.. _draft mode: https://help.github.com/en/articles/creating-a-pull-request-from-a-fork |
| 129 | + |
| 130 | +5. Get the necessary tools: :ref:`set-up-dev`. |
| 131 | + |
| 132 | +6. Make commits of **small, logical units of work**. |
| 133 | + We should be able to use `git bisect`_ to find the origin of bugs. |
| 134 | + Make sure you :ref:`sign-off <sign-your-work>` on all your commits:: |
| 135 | + |
| 136 | + $ git commit -s |
| 137 | + |
| 138 | + And finally, please write :ref:`clear commit messages <commit-messages>`! |
| 139 | + |
| 140 | +.. _git bisect: https://git-scm.com/docs/git-bisect |
| 141 | + |
| 142 | +7. Check that all **tests** (including your *new* ones) succeed:: |
| 143 | + |
| 144 | + $ make test |
| 145 | + |
| 146 | + If this fails on your local machine, there is a good risk that it will also |
| 147 | + fail on Travis, preventing your pull request from being merged. |
| 148 | + |
| 149 | +8. `Project maintainers`_ may **comment on your work** as you progress. |
| 150 | + If they don't and you would like some feedback, feel free to mention_ one of |
| 151 | + them in your pull request. |
| 152 | + |
| 153 | +.. _project maintainers: https://github.com/zalando-incubator/zelt/blob/master/MAINTAINERS |
| 154 | +.. _mention: https://github.blog/2011-03-23-mention-somebody-they-re-notified/ |
| 155 | + |
| 156 | +9. As explained in the :ref:`release-process` section, in Zelt, **each |
| 157 | + pull request merged** in the ``master`` branch becomes a **new release** on |
| 158 | + PyPI. |
| 159 | + Therefore, a few files need to be updated with a **new version number**, and |
| 160 | + :file:`docs/Changelog.rst` should probably contain a description of your |
| 161 | + contributions. |
| 162 | + **Everything is explained** in :ref:`release-process`. |
| 163 | + |
| 164 | +10. You are welcome to add your name in our :ref:`contributors` file |
| 165 | + (:file:`docs/Contributors.rst`). |
| 166 | + This is of course optional, but we would be happy to remember and showcase |
| 167 | + the help you provided! |
| 168 | + |
| 169 | +11. When you are done, mark your draft pull request as `Ready for review`_. |
| 170 | + This will automatically request a **code review** from all `project |
| 171 | + maintainers`_. |
| 172 | + |
| 173 | + Make sure your contributions respect :ref:`Zelt's conventions |
| 174 | + <project-conventions>` before that! |
| 175 | + |
| 176 | +.. _ready for review: https://help.github.com/en/articles/changing-the-stage-of-a-pull-request |
| 177 | + |
| 178 | +12. Your pull request must be approved 👍 by two `project maintainers`_ before |
| 179 | + it can be merged. |
| 180 | + |
| 181 | +**Thank you** for your contributions! |
| 182 | + |
| 183 | +.. _documentation: |
| 184 | + |
| 185 | +Documentation |
| 186 | +------------- |
| 187 | + |
| 188 | +It is important that *all* features of Zelt are **documented**: |
| 189 | + |
| 190 | +- **user-facing features**, such as new command-line options: |
| 191 | + if our users don't know these features exist, they will not use them and |
| 192 | + Zelt will be less useful to them; |
| 193 | + |
| 194 | +- **contributor-facing features**, like internal APIs, design decisions, and |
| 195 | + contribution workflows: if our potential contributors struggle finding the |
| 196 | + right place to contribute, or cannot get a working development environment, |
| 197 | + the barrier of entry will be too high and the project will not benefit from |
| 198 | + their valuable contributions. |
| 199 | + |
| 200 | +Zelt uses Sphinx_ to make the documentation accessible and readable to |
| 201 | +anyone with a web browser. |
| 202 | +It also makes it easy to link user documentation (in :file:`docs/*.rst`) and |
| 203 | +contributor documentation (as docstrings_ in Zelt's Python source files) |
| 204 | +when appropriate. |
| 205 | + |
| 206 | +.. _docstrings: https://en.wikipedia.org/wiki/Docstring |
| 207 | + |
| 208 | +Sphinx is automatically installed during the :ref:`set-up-dev` step. |
| 209 | +**You can easily build the documentation** on your own machine by running |
| 210 | +``make docs`` at the root of the repository. |
| 211 | +This converts the reST files under the :file:`docs/` directory into HTML files |
| 212 | +under :file:`docs/_build/html/`, so you can do something like:: |
| 213 | + |
| 214 | + $ firefox docs/_build/html/index.html |
| 215 | + |
| 216 | +to start browsing the documentation locally. |
| 217 | + |
| 218 | +.. note:: |
| 219 | + |
| 220 | + Be careful not to track these generated HTML files with git. |
| 221 | + The reST files and docstrings are the only source of truth. |
| 222 | + |
| 223 | +.. _commit-messages: |
| 224 | + |
| 225 | +Commit messages |
| 226 | +--------------- |
| 227 | + |
| 228 | +Ideally, your commit messages answer two questions: |
| 229 | +**what changed** and **why?** |
| 230 | + |
| 231 | +The message's first line should describe the "what". |
| 232 | +The rest of the message (separated from the first line by an empty line) |
| 233 | +should explain the "why". |
| 234 | + |
| 235 | +.. _sign-your-work: |
| 236 | + |
| 237 | +Sign your work / DCO |
| 238 | +-------------------- |
| 239 | + |
| 240 | +All contributions to Zelt (including pull requests) must agree to the |
| 241 | +`Developer Certificate of Origin (DCO) version 1.1`__. |
| 242 | +This is exactly the same one created and used by the Linux kernel developers: |
| 243 | +a certification by a developer that they have the right to submit their |
| 244 | +contribution to the project. |
| 245 | + |
| 246 | +__ http://developercertificate.org/ |
| 247 | + |
| 248 | +Simply submitting a contribution (commits) implies this agreement. |
| 249 | +However, **please include a "Signed-off-by" line** in every commit -- that line |
| 250 | +is a conventional way to confirm that you agree with the DCO. |
| 251 | +You can do that easily with git's ``-s`` option:: |
| 252 | + |
| 253 | + $ git commit -s |
| 254 | + |
| 255 | +You can automate this with a `git hook`_. |
| 256 | + |
| 257 | +.. _git hook: https://stackoverflow.com/questions/15015894 |
| 258 | + /git-add-signed-off-by-line-using-format-signoff-not-working |
| 259 | + |
| 260 | +.. centered:: Have fun, and happy hacking! |
0 commit comments