CONTRIBUTING.rst

Contributing to Waffle

This is a Jazzband project. By contributing you agree to abide by the Contributor Code of Conduct and follow the guidelines.

Waffle is pretty simple to hack, and has a decent test suite! Here's how to patch Waffle, add tests, run them, and contribute changes.

Please open a new issue to discuss a new feature before beginning work on it. Not all suggestions are accepted. The :ref:`Goals <about-goals>` may help guide which features are likely to be accepted.

Set Up

Setting up an environment is easy! You'll want virtualenv and pip, then just create a new virtual environment and install the requirements:

$ mkvirtualenv waffle
$ pip install -r requirements.txt

Done!

Writing Patches

Fork Waffle and create a new branch off master for your patch. Run the tests often:

$ ./run.sh test

Try to keep each branch to a single feature or bugfix.

Note

To update branches, please rebase onto master, do not merge master into your branch.

Submitting Patches

Open a pull request on GitHub!

Before a pull request gets merged, it should be rebased onto master and squashed into a minimal set of commits. Each commit should include the necessary code, test, and documentation changes for a single "piece" of functionality.

To be mergeable, patches must:

• be rebased onto the latest master,
• be automatically mergeable,
• not break existing tests,
• not change existing tests without a very good reason,
• add tests for new code (bug fixes should include regression tests, new features should have relevant tests),
• not introduce any new ruff errors (run ./run.sh lint),
• not introduce any new mypy errors (run ./run.sh typecheck),
• include updated source translations (run ./run.sh makemessages and ./run.sh compilemessages),
• document any new features, and
• have a good commit message.

Regressions tests should fail without the rest of the patch and pass with it.