| Jon Wayne Parrott | 377f293 | 2016-10-04 10:20:36 -0700 | [diff] [blame] | 1 | Contributing |
| 2 | ============ |
| 3 | |
| 4 | #. **Please sign one of the contributor license agreements below.** |
| 5 | #. Fork the repo, develop and test your code changes, add docs. |
| 6 | #. Make sure that your commit messages clearly describe the changes. |
| 7 | #. Send a pull request. |
| 8 | |
| 9 | Here are some guidelines for hacking on ``google-auth-library-python``. |
| 10 | |
| 11 | Making changes |
| 12 | -------------- |
| 13 | |
| 14 | A few notes on making changes to ``google-auth-libary-python``. |
| 15 | |
| 16 | - If you've added a new feature or modified an existing feature, be sure to |
| 17 | add or update any applicable documentation in docstrings and in the |
| 18 | documentation (in ``docs/``). You can re-generate the reference documentation |
| 19 | using ``tox -e docgen``. |
| 20 | |
| 21 | - The change must work fully on the following CPython versions: 2.7, |
| 22 | 3.4, and 3.5 across macOS, Linux, and Windows. |
| 23 | |
| 24 | - The codebase *must* have 100% test statement coverage after each commit. |
| 25 | You can test coverage via ``tox -e cover``. |
| 26 | |
| 27 | Testing changes |
| 28 | --------------- |
| 29 | |
| 30 | To test your changes, run unit tests with ``tox``:: |
| 31 | |
| 32 | $ tox -e py27 |
| 33 | $ tox -e py34 |
| 34 | $ tox -e py35 |
| 35 | |
| 36 | Coding Style |
| 37 | ------------ |
| 38 | |
| 39 | This library is PEP8 & Pylint compliant. Our Pylint config is defined at |
| 40 | ``pylintrc`` for package code and ``pylintrc.tests`` for test code. Use |
| 41 | ``tox`` to check for non-compliant code:: |
| 42 | |
| 43 | $ tox -e lint |
| 44 | |
| 45 | Documentation Coverage and Building HTML Documentation |
| 46 | ------------------------------------------------------ |
| 47 | |
| 48 | If you fix a bug, and the bug requires an API or behavior modification, all |
| 49 | documentation in this package which references that API or behavior must be |
| 50 | changed to reflect the bug fix, ideally in the same commit that fixes the bug |
| 51 | or adds the feature. |
| 52 | |
| 53 | To build and review docs use ``tox``:: |
| 54 | |
| 55 | $ tox -e docs |
| 56 | |
| 57 | The HTML version of the docs will be built in ``docs/_build/html`` |
| 58 | |
| 59 | Versioning |
| 60 | ---------- |
| 61 | |
| 62 | This library follows `Semantic Versioning`_. |
| 63 | |
| 64 | .. _Semantic Versioning: http://semver.org/ |
| 65 | |
| 66 | It is currently in major version zero (``0.y.z``), which means that anything |
| 67 | may change at any time and the public API should not be considered |
| 68 | stable. |
| 69 | |
| 70 | Contributor License Agreements |
| 71 | ------------------------------ |
| 72 | |
| 73 | Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA): |
| 74 | |
| 75 | - **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need to sign an `individual CLA <https://developers.google.com/open-source/cla/individual>`__. |
| 76 | - **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a `corporate CLA <https://developers.google.com/open-source/cla/corporate>`__. |
| 77 | |
| 78 | You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests. |