1How to Contribute 2================= 3 4Contributions are welcome! Not familiar with the codebase yet? No problem! 5There are many ways to contribute to open source projects: reporting bugs, 6helping with the documentation, spreading the word and of course, adding 7new features and patches. 8 9.. note:: 10 11 There's currently a feature freeze until the basic code modernization for 12 the 2.0 release is finished. Have a look at the ``ROADMAP.md`` for a status 13 on its progress. 14 15Getting Started 16--------------- 17#. Make sure you have a GitHub account. 18#. Open a `new issue`_, assuming one does not already exist. 19#. Clearly describe the issue including steps to reproduce when it is a bug. 20 21Making Changes 22-------------- 23* Fork_ the repository on GitHub. 24* Create a topic branch from where you want to base your work. 25* This is usually the ``master`` branch. 26* Please avoid working directly on ``master`` branch. 27* Make commits of logical units (if needed rebase your feature branch before 28 submitting it). 29* Make sure your commit messages are in the `proper format`_. 30* If your commit fixes an open issue, reference it in the commit message (#15). 31* Make sure you have added the necessary tests for your changes. 32* Run all the tests to assure nothing else was accidentally broken. 33* Install and enable pre-commit_ (``pip install pre-commit``, then ``pre-commit 34 install``) to ensure styleguides and codechecks are followed. CI will reject 35 a change that does not conform to the guidelines. 36* Don't forget to add yourself to AUTHORS_. 37 38These guidelines also apply when helping with documentation (actually, for 39typos and minor additions you might choose to `fork and edit`_). 40 41.. _pre-commit: https://pre-commit.com/ 42 43Submitting Changes 44------------------ 45* Push your changes to a topic branch in your fork of the repository. 46* Submit a `Pull Request`_. 47* Wait for maintainer feedback. 48 49First time contributor? 50----------------------- 51It's alright. We've all been there. 52 53Dont' know where to start? 54-------------------------- 55There are usually several TODO comments scattered around the codebase, maybe 56check them out and see if you have ideas, or can help with them. Also, check 57the `open issues`_ in case there's something that sparks your interest. What 58about documentation? I suck at english so if you're fluent with it (or notice 59any error), why not help with that? In any case, other than GitHub help_ pages, 60you might want to check this excellent `Effective Guide to Pull Requests`_ 61 62.. _`the repository`: https://github.com/pyeve/cerberus 63.. _AUTHORS: https://github.com/pyeve/cerberus/blob/master/AUTHORS 64.. _`open issues`: https://github.com/pyeve/cerberus/issues 65.. _`new issue`: https://github.com/pyeve/cerberus/issues/new 66.. _Fork: https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo 67.. _`proper format`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html 68.. _help: https://docs.github.com/ 69.. _`Effective Guide to Pull Requests`: https://codeinthehole.com/writing/pull-requests-and-other-good-practices-for-teams-using-github/ 70.. _`fork and edit`: https://github.blog/2011-04-26-forking-with-the-edit-button/ 71.. _`Pull Request`: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request 72