README.rst 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189
  1. ===================
  2. mozilla-django-oidc
  3. ===================
  4. .. image:: https://badge.fury.io/py/mozilla-django-oidc.svg
  5. :target: https://badge.fury.io/py/mozilla-django-oidc
  6. .. image:: https://travis-ci.org/mozilla/mozilla-django-oidc.svg?branch=master
  7. :target: https://travis-ci.org/mozilla/mozilla-django-oidc
  8. .. image:: https://codecov.io/gh/mozilla/mozilla-django-oidc/branch/master/graph/badge.svg
  9. :target: https://codecov.io/gh/mozilla/mozilla-django-oidc
  10. .. image:: https://circleci.com/gh/mozilla/mozilla-django-oidc/tree/master.svg?style=svg
  11. :target: https://circleci.com/gh/mozilla/mozilla-django-oidc/tree/master
  12. A lightweight authentication and access management library for integration with OpenID Connect enabled authentication services.
  13. Documentation
  14. -------------
  15. The full documentation is at `<https://mozilla-django-oidc.readthedocs.io>`_.
  16. Running Unit Tests
  17. -------------------
  18. Use ``tox`` to run as many different versions of Python you have. If you
  19. don't have ``tox`` installed (and executable) already you can either
  20. install it in your system Python or `<https://pypi.python.org/pypi/pipsi>`_.
  21. Once installed, simply execute in the project root directory.
  22. .. code-block:: shell
  23. $ tox
  24. ``tox`` will do the equivalent of installing virtual environments for every
  25. combination mentioned in the ``tox.ini`` file. If your system, for example,
  26. doesn't have ``python3.4`` those ``tox`` tests will be skipped.
  27. For a faster test-rinse-repeat cycle you can run tests in a specific
  28. environment with a specific version of Python and specific version of
  29. Django of your choice. Here is such an example:
  30. .. code-block:: shell
  31. $ virtualenv -p /path/to/bin/python3.5 venv
  32. $ source venv
  33. (venv) $ pip install Django==1.11.2
  34. (venv) $ pip install -r tests/requirements.txt
  35. (venv) $ DJANGO_SETTINGS_MODULE=tests.settings django-admin.py test
  36. Measuring code coverage, continuing the steps above:
  37. .. code-block:: shell
  38. (venv) $ pip install coverage
  39. (venv) $ DJANGO_SETTINGS_MODULE=tests.settings coverage run --source mozilla_django_oidc `which django-admin.py` test
  40. (venv) $ coverage report
  41. (venv) $ coverage html
  42. (venv) $ open htmlcov/index.html
  43. Local development
  44. -----------------
  45. The local development setup is based on Docker so you need the following installed in your system:
  46. * `docker`
  47. * `docker-compose`
  48. You will also need to edit your ``hosts`` file to resolve ``testrp`` and ``testprovider`` hostnames to ``127.0.0.1``.
  49. Running test services
  50. =====================
  51. To run the `testrp` and `testprovider` instances run the following:
  52. .. code-block:: shell
  53. (venv) $ docker-compose up -d testprovider testrp
  54. Then visit the testing django app on: ``http://testrp:8081``.
  55. The library source code is mounted as a docker volume and source code changes are reflected directly in.
  56. In order to test a change you need to restart the ``testrp`` service.
  57. .. code-block:: shell
  58. (venv) $ docker-compose stop testrp
  59. (venv) $ docker-compose up -d testrp
  60. Running integration tests
  61. =========================
  62. Integration tests are mounted as a volume to the docker containers. Tests can be run using the following command:
  63. .. code-block:: shell
  64. (venv) $ docker-compose run --service-ports testrunner
  65. Linting
  66. -------
  67. All code is checked with `<https://pypi.python.org/pypi/flake8>`_ in
  68. continuous integration. To make sure your code still passes all style guides
  69. install ``flake8`` and check:
  70. .. code-block:: shell
  71. $ flake8 mozilla_django_oidc tests
  72. .. note::
  73. When you run ``tox`` it also does a ``flake8`` run on the main package
  74. files and the tests.
  75. You can also run linting with ``tox``:
  76. .. code-block:: shell
  77. $ tox -e lint
  78. Releasing a new version
  79. ------------------------
  80. ``mozilla-django-oidc`` releases are hosted in `PyPI <https://pypi.python.org/pypi/mozilla-django-oidc>`_.
  81. Here are the steps you need to follow in order to push a new release:
  82. * Make sure that ``HISTORY.rst`` is up-to-date focusing mostly on backwards incompatible changes.
  83. Security vulnerabilities should be clearly marked in a "Security issues" section along with
  84. a level indicator of:
  85. * High: vulnerability facilitates data loss, data access, impersonation of admin, or allows access
  86. to other sites or components
  87. Users should upgrade immediately.
  88. * Medium: vulnerability endangers users by sending them to malicious sites or stealing browser
  89. data.
  90. Users should upgrade immediately.
  91. * Low: vulnerability is a nuissance to site staff and/or users
  92. Users should upgrade.
  93. * Bump the project version and create a commit for the new version.
  94. * You can use ``bumpversion`` for that. It is a tool to automate this procedure following the `semantic versioning scheme <http://semver.org/>`_.
  95. * For a patch version update (eg 0.1.1 to 0.1.2) you can run ``bumpversion patch``.
  96. * For a minor version update (eg 0.1.0 to 0.2.0) you can run ``bumpversion minor``.
  97. * For a major version update (eg 0.1.0 to 1.0.0) you can run ``bumpversion major``.
  98. * Create a `signed tag <https://git-scm.com/book/tr/v2/Git-Tools-Signing-Your-Work>`_ for that version
  99. Example::
  100. git tag -s 0.1.1 -m "Bump version: 0.1.0 to 0.1.1"
  101. * Push the signed tag to Github
  102. Example::
  103. git push origin 0.1.1
  104. The release is pushed automatically to PyPI using a travis deployment hook on every new tag.
  105. License
  106. -------
  107. This software is licensed under the MPL 2.0 license. For more info check the LICENSE file.
  108. Credits
  109. -------
  110. Tools used in rendering this package:
  111. * Cookiecutter_
  112. * `cookiecutter-djangopackage`_
  113. .. _Cookiecutter: https://github.com/audreyr/cookiecutter
  114. .. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage