Commit 10cc56d3 authored by Leo Pound Singer's avatar Leo Pound Singer

Convert refs to autosphinx

parent 9eefc3bc
Contributing
============
Contributors may familiarize themselves with Celery itself by going through the
`First Steps with Celery`_ tutorial.
.. _`First Steps with Celery`: http://docs.celeryproject.org/en/latest/getting-started/first-steps-with-celery.html
Development model
-----------------
GWCelery operates on a fork-and-merge development model (see `GitLab basics`_
for an introduction).
To contribute to GWCelery development, follow these steps:
1. `Create a personal fork of GWCelery`_.
2. Make your changes on a branch.
3. Open a merge request.
Note that GWCelery uses `fast-forward merges`_.
.. _`GitLab basics`: https://git.ligo.org/help/gitlab-basics/README.md
.. _`Create a personal fork of GWCelery`: https://git.ligo.org/emfollow/gwcelery/forks/new
.. _`fast-forward merges`: https://git.ligo.org/help/user/project/merge_requests/fast_forward_merge.md
Where new code should go
------------------------
New code will generally consist of adding `Celery tasks`_. Tasks are organized
by functionality into submodules of ``gwcelery.tasks``. If your new task does
not match with one of the existing submodules, please create a new submodule.
.. _`Celery tasks`: http://docs.celeryproject.org/en/latest/userguide/tasks.html
Guidelines for tasks
--------------------
- **Tasks should be short.** When deciding where a new task should go, start
from the following loose rules of thumb:
1. If it's less than a screenful of code, and related to functionality in
an existing module, then put the code in a new task in that module.
2. If it's up to a few screenfuls of code, or not related to functionality
in an existing module, then try to break it into a few smaller functions
or tasks and put it in a new module.
3. If it's more than a few screenfuls of code, or adds many additional
dependencies, then it should go in a separate package.
See also the note on `granularity`_ in the Celery manual's "`Tips and Best
Practices`_" section.
- **Tasks should avoid saving files to disk.** Output should be placed
directly in GraceDb. Temporary files that are written in ``/tmp`` are OK but
should be cleaned up promptly.
See also the Celery manual's notes on `data locality`_ and `state`_.
- **Dependencies should be installable by pip.** Dependencies of tasks should
be listed in the `requirements.txt`_ file so that they are installed
automatically when GWCelery is installed with `pip`_.
.. _`granularity`: http://docs.celeryproject.org/en/latest/userguide/tasks.html#granularity
.. _`Tips and Best Practices`: http://docs.celeryproject.org/en/latest/userguide/tasks.html#tips-and-best-practices
.. _`data locality`: http://docs.celeryproject.org/en/latest/userguide/tasks.html#data-locality
.. _`state`: http://docs.celeryproject.org/en/latest/userguide/tasks.html#state
.. _`requirements.txt`: https://git.ligo.org/emfollow/gwcelery/blob/master/requirements.txt
.. _`pip`: https://pip.pypa.io/
Unit tests
----------
Unit tests and code coverage measurement are run automatically for every branch
and for every merge request. New code contributions must have 100% test
coverage. Modifications to existing code must not decrease test coverage. To
run the unit tests and measure code coverage, run the following commands in the
top directory of your local source checkout::
$ pip install pytest-cov
$ python setup.py test --addopts='--cov --cov-report html'
This will save a coverage report that you can view in a web browser as
``htmlcov/index.html``.
Code style
----------
Code should be written in the :pep:`8` style and must pass linting by
`Flake8`_. To check code style, run the following commands in the top of your
source directory::
$ pip install flake8 pep8-naming
$ flake8 --show-source .
.. _Flake8: http://flake8.pycqa.org/en/latest/
Documentation
-------------
Documentation strings should be written in the `Numpydoc style`_.
.. _`Numpydoc style`: http://numpydoc.readthedocs.io/
See https://gwcelery.readthedocs.io/en/latest/contributing.html
../CONTRIBUTING.rst
\ No newline at end of file
Contributing
============
Contributors may familiarize themselves with Celery itself by going through the
:ref:`celery:first-steps` tutorial.
Development model
-----------------
GWCelery operates on a fork-and-merge development model (see `GitLab basics`_
for an introduction).
To contribute to GWCelery development, follow these steps:
1. `Create a personal fork of GWCelery`_.
2. Make your changes on a branch.
3. Open a merge request.
Note that GWCelery uses `fast-forward merges`_.
.. _`GitLab basics`: https://git.ligo.org/help/gitlab-basics/README.md
.. _`Create a personal fork of GWCelery`: https://git.ligo.org/emfollow/gwcelery/forks/new
.. _`fast-forward merges`: https://git.ligo.org/help/user/project/merge_requests/fast_forward_merge.md
Where new code should go
------------------------
New code will generally consist of adding :ref:`Celery tasks <celery:guide-tasks>`.
Tasks are organized by functionality into submodules of :mod:`gwcelery.tasks`.
If your new task does not match with one of the existing submodules, please
create a new submodule.
Guidelines for tasks
--------------------
- **Tasks should be short.** When deciding where a new task should go, start
from the following loose rules of thumb:
1. If it's less than a screenful of code, and related to functionality in
an existing module, then put the code in a new task in that module.
2. If it's up to a few screenfuls of code, or not related to functionality
in an existing module, then try to break it into a few smaller functions
or tasks and put it in a new module.
3. If it's more than a few screenfuls of code, or adds many additional
dependencies, then it should go in a separate package.
See also the note on :ref:`celery:task-granularity` in the Celery manual's
:ref:`celery:task-best-practices` section.
- **Tasks should avoid saving files to disk.** Output should be placed
directly in GraceDb. Temporary files that are written in ``/tmp`` are OK but
should be cleaned up promptly.
See also the Celery manual's notes on :ref:`task-celery:task-data-locality`
and :ref:`celery:task-state`.
- **Dependencies should be installable by pip.** Dependencies of tasks should
be listed in the `requirements.txt`_ file so that they are installed
automatically when GWCelery is installed with `pip`_.
.. _`requirements.txt`: https://git.ligo.org/emfollow/gwcelery/blob/master/requirements.txt
.. _`pip`: https://pip.pypa.io/
Unit tests
----------
Unit tests and code coverage measurement are run automatically for every branch
and for every merge request. New code contributions must have 100% test
coverage. Modifications to existing code must not decrease test coverage. To
run the unit tests and measure code coverage, run the following commands in the
top directory of your local source checkout::
$ pip install pytest-cov
$ python setup.py test --addopts='--cov --cov-report html'
This will save a coverage report that you can view in a web browser as
``htmlcov/index.html``.
Code style
----------
Code should be written in the :pep:`8` style and must pass linting by
`Flake8`_. To check code style, run the following commands in the top of your
source directory::
$ pip install flake8 pep8-naming
$ flake8 --show-source .
.. _Flake8: http://flake8.pycqa.org/en/latest/
Documentation
-------------
Documentation strings should be written in the `Numpydoc style`_.
.. _`Numpydoc style`: http://numpydoc.readthedocs.io/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment