You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

CONTRIBUTING.rst 4.1KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120
  1. .. |br| raw:: html
  2. <br />
  3. ############
  4. Contributing
  5. ############
  6. Contributions are always welcome and appreciated! Here are some ways you can contribut.
  7. ******
  8. Issues
  9. ******
  10. You can and should open an issue for any of the following reasons:
  11. * you found a bug; steps for reproducing, or a pull request with a failing test case will be greatly appreciated
  12. * you wanted to do something but did not find a way to do it after reading the documentation
  13. * you believe the current way of doing something is more complicated or less elegant than it can be
  14. * a related feature that you want is missing from the package
  15. Please always check for existing issues before opening a new issue.
  16. *************
  17. Pull requests
  18. *************
  19. You want to contribute some code? Great! Here are a few steps to get you started:
  20. #. **Fork the repository on GitHub**
  21. #. **Clone your fork and create a branch for the code you want to add**
  22. #. **Create a new virtualenv and install the package in development mode**
  23. .. code:: console
  24. $ virtualenv venv
  25. $ source venv/bin/activate
  26. (venv) $ python -m pip install -U pip setuptools
  27. (venv) $ pip install -U -e .[validation]
  28. (venv) $ pip install -U -r requirements/dev.txt
  29. #. **Make your changes and check them against the test project**
  30. .. code:: console
  31. (venv) $ cd testproj
  32. (venv) $ python manage.py migrate
  33. (venv) $ python manage.py runserver
  34. (venv) $ firefox localhost:8000/swagger/
  35. #. **Update the tests if necessary**
  36. You can find them in the ``tests`` directory.
  37. If your change modifies the expected schema output, you should regenerate the reference schema at
  38. ``tests/reference.yaml``:
  39. .. code:: console
  40. (venv) $ python testproj/manage.py generate_swagger ../tests/reference.yaml --overwrite --user admin --url http://test.local:8002/
  41. After checking the git diff to verify that no unexpected changes appeared, you should commit the new
  42. ``reference.yaml`` together with your changes.
  43. #. **Run tests. The project is setup to use tox and pytest for testing**
  44. .. code:: console
  45. # install test dependencies
  46. (venv) $ pip install -U -r requirements/test.txt
  47. # run tests in the current environment, faster than tox
  48. (venv) $ pytest -n auto --cov
  49. # (optional) sort imports with isort and check flake8 linting
  50. (venv) $ isort --apply
  51. (venv) $ flake8 src/drf_yasg testproj tests setup.py
  52. # (optional) run tests for other python versions in separate environments
  53. (venv) $ tox
  54. #. **Update documentation**
  55. If the change modifies behaviour or adds new features, you should update the documentation and ``README.rst``
  56. accordingly. Documentation is written in reStructuredText and built using Sphinx. You can find the sources in the
  57. ``docs`` directory.
  58. To build and check the docs, run
  59. .. code:: console
  60. (venv) $ tox -e docs
  61. #. **Push your branch and submit a pull request to the master branch on GitHub**
  62. Incomplete/Work In Progress pull requests are encouraged, because they allow you to get feedback and help more
  63. easily.
  64. #. **Your code must pass all the required travis jobs before it is merged**
  65. As of now, this consists of running on Python 2.7, 3.5, 3.6 and 3.7, and building the docs succesfully.
  66. ******************
  67. Maintainer's notes
  68. ******************
  69. Release checklist
  70. =================
  71. * update ``docs/changelog.rst`` with changes since the last tagged version
  72. * commit & tag the release - ``git tag x.x.x -m "Release version x.x.x"``
  73. * push using ``git push --follow-tags``
  74. * verify that `Travis`_ has built the tag and succesfully published the release to `PyPI`_
  75. * publish release notes `on GitHub`_
  76. * start the `ReadTheDocs build`_ if it has not already started
  77. * deploy the live demo `on Heroku`_
  78. .. _Travis: https://travis-ci.org/axnsan12/drf-yasg/builds
  79. .. _PyPI: https://pypi.org/project/drf-yasg/
  80. .. _on GitHub: https://github.com/axnsan12/drf-yasg/releases
  81. .. _ReadTheDocs build: https://readthedocs.org/projects/drf-yasg/builds/
  82. .. _on Heroku: https://dashboard.heroku.com/pipelines/412d1cae-6a95-4f5e-810b-94869133f36a