============
Contributing
============

Contributions are welcome, preferably via pull request. Check the github issues to see
what needs work, or if you have an idea for a new feature it may be worth raising an
issue to discuss it first.


Making changes
==============

The easiest way to work on this is to fork the project on GitHub, then run the
examples using your local copy of dropulous.

There's no build step for development -
``examples/index.html`` loads ``../src/dropulous.js`` and ``../src/dropulous.css``
directly:

.. code-block:: bash

    # replace radiac with your username after forking
    git clone https://github.com/radiac/dropulous.git
    cd dropulous/repo
    open examples/index.html

While ``examples/index.html`` tests the source files directly, you can test the versions
built for distribution using the files ``test/dist_script.html`` and
``test/dist_module.html``:

.. code-block:: bash

    # Build the dist/ files once...
    make build
    # ... or run a watcher which will rebuild after every save
    make watch

    open test/dist_script.html
    open test/dist_module.html


Testing
=======

It's always easier to merge PRs when they come with tests.

Run the tests with ``make`` - this runs everything in Docker, so you don't need Node
or a browser installed locally:

.. code-block:: bash

    make test

We only aim to support the latest versions of mainstream browsers - Chrome, Edge,
Firefox and Safari. The automated tests run in Chrome and Firefox.


Building documentation
=======================

Install the doc requirements (with ``pip`` or `uv
<https://docs.astral.sh/uv/>`_) and build once:

.. code-block:: bash

    uv pip install -r docs/requirements.txt
    sphinx-build -b html docs docs/_build/html

Or use ``sphinx-autobuild`` to rebuild and reload in the browser as you edit:

.. code-block:: bash

    sphinx-autobuild docs docs/_build/html