Skip to content

Contributing

Contributions are welcome — bug reports, documentation improvements, and code fixes all help make Raspi-Sump better.

Reporting Bugs

Before opening an issue, run rsumpsupport to collect system information:

rsumpsupport

Then open an issue in the issue tracker and include:

  • A clear description of the problem
  • Steps to reproduce
  • The support file generated by rsumpsupport

Improving Documentation

Documentation is written in Markdown and lives in the docs/ folder of the raspi-sump repository. Each page has an Edit link at the top that takes you directly to the file on GitHub.

To submit a documentation fix:

  1. Fork the repository on GitHub
  2. Edit the relevant Markdown file in docs/
  3. Submit a pull request against the devel branch

Contributing Code

  1. Open an issue in the tracker to discuss the change before submitting a pull request
  2. Fork the repository on GitHub
  3. Create a branch off devel for your change — never branch off main
  4. Make your changes, ensure all tests pass, then submit a pull request against devel

Guidelines

  1. Open an issue first — discuss the proposed change before writing code.

  2. Target the devel branch — do not submit pull requests against main.

  3. License — all code submitted must be your own or redistributable under the Apache 2.0 License.

  4. No external services — Raspi-Sump must not depend on external services that require a login or are subject to EULA changes. Python 3 standard library and Debian-packaged libraries are preferred. The one exception is Mastodon, which is open source and self-hostable.

  5. No CDN links — all JavaScript and CSS libraries must be bundled in raspisump/static/. Raspi-Sump runs as a LAN appliance and must function without internet access.

  6. Debian packaging — new Python dependencies must be added to debian/control as well as the code. Contributions must not break the .deb build (dpkg-buildpackage -us -uc -b).

  7. Code style — follow PEP 8 for code style and PEP 257 for docstrings. Add a docstring to every function. Add comments where the intent is not immediately obvious.

  8. Tests — new functionality must include a unittest. All existing tests must pass. Run the test suite with:

    bash pytest tests/

    GPIO is fully mocked — no hardware required to run tests.

  9. AI assistance — you may use AI assistants to help write code. Be honest about your usage. Do not submit code you do not understand or that has no clear purpose.

  10. Feature acceptance — not all new features will be accepted. The Apache 2.0 license allows and welcomes you to fork and release an altered version under any compatible license.

Getting in Touch

If you want to contribute, join the Discord group — there is a #code-discussion channel. It is not mandatory but makes collaboration much easier. Email alaudet@linuxnorth.org to request an invite link.

License

Raspi-Sump is released under the Apache 2.0 License. By submitting a pull request you agree to license your contribution under the same terms.