django-downloadview/CONTRIBUTING.rst

############
Contributing
############


.. image:: https://jazzband.co/static/img/jazzband.svg
   :target: https://jazzband.co/
   :alt: Jazzband

This is a `Jazzband <https://jazzband.co>`_ project. By contributing you agree to abide by the `Contributor Code of Conduct <https://jazzband.co/about/conduct>`_ and follow the `guidelines <https://jazzband.co/about/guidelines>`_.


This document provides guidelines for people who want to contribute to
``django-downloadview``.


**************
Create tickets
**************

Please use the `bugtracker`_ **before** starting some work:

* check if the bug or feature request has already been filed. It may have been
  answered too!

* else create a new ticket.

* if you plan to contribute, tell us, so that we are given an opportunity to
  give feedback as soon as possible.

* Then, in your commit messages, reference the ticket with some
  ``refs #TICKET-ID`` syntax.


******************
Use topic branches
******************

* Work in branches.

* Prefix your branch with the ticket ID corresponding to the issue. As an
  example, if you are working on ticket #23 which is about contribute
  documentation, name your branch like ``23-contribute-doc``.

* If you work in a development branch and want to refresh it with changes from
  master, please `rebase`_ or `merge-based rebase`_, i.e. do not merge master.


***********
Fork, clone
***********

Clone ``django-downloadview`` repository (adapt to use your own fork):

.. code:: sh

   git clone git@github.com:jazzband/django-downloadview.git
   cd django-downloadview/


*************
Usual actions
*************

The ``Makefile`` is the reference card for usual actions in development
environment:

* Install development toolkit with `pip`_: ``make develop``.

* Run tests with `tox`_: ``make test``.

* Build documentation: ``make documentation``. It builds `Sphinx`_
  documentation in ``var/docs/html/index.html``.

* Release project with `zest.releaser`_: ``make release``.

* Cleanup local repository: ``make clean``, ``make distclean`` and
  ``make maintainer-clean``.

See also ``make help``.


*********************
Demo project included
*********************

The ``demo`` included in project's repository is part of the tests and
documentation. Maintain it along with code and documentation.


.. rubric:: Notes & references

.. target-notes::

.. _`bugtracker`:
   https://github.com/jazzband/django-downloadview/issues
.. _`rebase`: http://git-scm.com/book/en/Git-Branching-Rebasing
.. _`merge-based rebase`: https://tech.people-doc.com/psycho-rebasing.html
.. _`pip`: https://pypi.python.org/pypi/pip/
.. _`tox`: https://tox.readthedocs.io/
.. _`Sphinx`: https://pypi.python.org/pypi/Sphinx/
.. _`zest.releaser`: https://pypi.python.org/pypi/zest.releaser/
Refs #74 - Switched to tox as test-environment manager. Added flake8 to the test suite. Dropped python 2.6 tests. Makefile no longer creates a virtualenv. 2014-02-10 00:27:14 +00:00			`############`
			`Contributing`
			`############`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Be ready for Jazzband move. 2020-09-17 13:48:41 +00:00
			`.. image:: https://jazzband.co/static/img/jazzband.svg`
			`:target: https://jazzband.co/`
			`:alt: Jazzband`

			This is a `Jazzband <https://jazzband.co>`_ project. By contributing you agree to abide by the `Contributor Code of Conduct <https://jazzband.co/about/conduct>`_ and follow the `guidelines <https://jazzband.co/about/guidelines>`_.


Refs #74 - Switched to tox as test-environment manager. Added flake8 to the test suite. Dropped python 2.6 tests. Makefile no longer creates a virtualenv. 2014-02-10 00:27:14 +00:00			`This document provides guidelines for people who want to contribute to`
Run pre-commit on all files 2024-08-05 08:51:17 +00:00			``django-downloadview``.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00

			`**************`
			`Create tickets`
			`**************`

			Please use the `bugtracker`_ before starting some work:

			`* check if the bug or feature request has already been filed. It may have been`
			`answered too!`

			`* else create a new ticket.`

			`* if you plan to contribute, tell us, so that we are given an opportunity to`
			`give feedback as soon as possible.`

			`* Then, in your commit messages, reference the ticket with some`
			``refs #TICKET-ID`` syntax.


Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`******************`
			`Use topic branches`
			`******************`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`* Work in branches.`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
			`* Prefix your branch with the ticket ID corresponding to the issue. As an`
			`example, if you are working on ticket #23 which is about contribute`
			documentation, name your branch like ``23-contribute-doc``.

			`* If you work in a development branch and want to refresh it with changes from`
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			master, please `rebase`_ or `merge-based rebase`_, i.e. do not merge master.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00

Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`***********`
			`Fork, clone`
			`***********`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Run pre-commit on all files 2024-08-05 08:51:17 +00:00			Clone ``django-downloadview`` repository (adapt to use your own fork):
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`.. code:: sh`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Be ready for Jazzband move. 2020-09-17 13:48:41 +00:00			`git clone git@github.com:jazzband/django-downloadview.git`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00			`cd django-downloadview/`


Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`*************`
			`Usual actions`
			`*************`

Run pre-commit on all files 2024-08-05 08:51:17 +00:00			The ``Makefile`` is the reference card for usual actions in development
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`environment:`

			* Install development toolkit with `pip`_: ``make develop``.

			* Run tests with `tox`_: ``make test``.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			* Build documentation: ``make documentation``. It builds `Sphinx`_
Run pre-commit on all files 2024-08-05 08:51:17 +00:00			documentation in ``var/docs/html/index.html``.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			* Release project with `zest.releaser`_: ``make release``.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			* Cleanup local repository: ``make clean``, ``make distclean`` and
			``make maintainer-clean``.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			See also ``make help``.
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00

Refs #16 - Improved documentation for Nginx optimizations (references to demo project). Refs #18 - Moved temporary_media_root utility from demoproject.download.tests to django_downloadview.test. 2012-12-10 10:05:28 +00:00			`*********************`
			`Demo project included`
			`*********************`

Run pre-commit on all files 2024-08-05 08:51:17 +00:00			The ``demo`` included in project's repository is part of the tests and
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			`documentation. Maintain it along with code and documentation.`
Refs #16 - Improved documentation for Nginx optimizations (references to demo project). Refs #18 - Moved temporary_media_root utility from demoproject.download.tests to django_downloadview.test. 2012-12-10 10:05:28 +00:00

Refs #74 - Switched to tox as test-environment manager. Added flake8 to the test suite. Dropped python 2.6 tests. Makefile no longer creates a virtualenv. 2014-02-10 00:27:14 +00:00			`.. rubric:: Notes & references`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00
			`.. target-notes::`

Run pre-commit on all files 2024-08-05 08:51:17 +00:00			.. _`bugtracker`:
Be ready for Jazzband move. 2020-09-17 13:48:41 +00:00			`https://github.com/jazzband/django-downloadview/issues`
Reviewed documentation. Preparing first public release. 2012-12-04 10:47:37 +00:00			.. _`rebase`: http://git-scm.com/book/en/Git-Branching-Rebasing
Another broken link. 2020-01-07 13:22:08 +00:00			.. _`merge-based rebase`: https://tech.people-doc.com/psycho-rebasing.html
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			.. _`pip`: https://pypi.python.org/pypi/pip/
Another broken link. 2020-01-07 13:22:08 +00:00			.. _`tox`: https://tox.readthedocs.io/
Reviewed Makefile, development environment and contributor guide. 2014-03-03 13:38:33 +00:00			.. _`Sphinx`: https://pypi.python.org/pypi/Sphinx/
			.. _`zest.releaser`: https://pypi.python.org/pypi/zest.releaser/