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:

# 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:

# 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:

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) and build once:

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:

sphinx-autobuild docs docs/_build/html