.. _developing-locust:

=================
Developing Locust
=================

You want to contribute to Locust? Great! Here is a list of `open bugs/feature requests <https://github.com/locustio/locust/>`_.

Install Locust for development
==============================

Fork Locust on `GitHub <https://github.com/locustio/locust/>`_ and then run

.. code-block:: console

    $ git clone git://github.com/<YourName>/locust.git # clone the repo
    $ pip3 install -e locust/                          # install in editable mode

Now the ``locust`` command will run *your* code with no need for reinstalling after making changes.

If you want to contribute back to us, make a branch *in your repo*, push your changes there and then `open a PR on github <https://github.com/locustio/locust/compare>`_. Before you open a pull request, make sure the tests work. And if you are adding a feature, make sure it is documented.

Running tests
=============

To be able to run Locust's test on different Python versions we use `tox <https://tox.readthedocs.io/en/stable/>`_. 
You can install tox by running:

.. code-block:: console

    pip3 install tox

Then you can run the tests by just invoking tox in the Locust project root directory:

.. code-block:: console

    tox

Format code
===========

Locust follows the `black <https://github.com/psf/black>`_ formatting standard. So please adhere to it

.. code-block:: console

    pip3 install black
    python -m black <file_to_be_formatted>


Build documentation
===================

To build the documentation you first need to install the required PyPI packages. You can do that by running 
the following command in the Locust project's root directory:

.. code-block:: console

    pip3 install -r docs/requirements.txt

Then you can build the documentation locally using:

.. code-block:: console

    make build_docs
    
Then the documentation should be build and available at ``docs/_build/index.html``.



Making changes to Locust's Web UI
=================================

The CSS styling for Locust's user interface is written in `SASS <https://sass-lang.com/>`_. 
In order to make changes to the CSS rules, you need to have SASS `installed <https://sass-lang.com/install>`_ 
and available on your ``PATH``.

Once you have SASS installed you can have the command line sass program compile the Locust ``.sass`` files
by running the following in the locust project's root path:

.. code-block:: console

    make sass_build


Or you can make sass watch for changes to the ``.sass`` files and automatically generate new CSS files by running:

.. code-block:: console

    make sass_watch

The CSS files that are generated by SASS should be checked into version control.
