Contributing

Wusel is developed by IT Beratung Hermann GmbH (ITBH) and is open under Apache-2.0. Contributions are welcome — on a simple, honest basis.

We would genuinely like to make Wusel better, and we are glad for help. The one thing we will not do is let the project be buried in noise; if that is where it heads, we will simply go back to developing it internally. So the guidelines below are less about process and more about good manners and real interest in moving the project forward.

For full transparency: Wusel itself is built with AI assistance — and that is not a euphemism for cutting corners. People still do the thinking. The design is reasoned out, specified, reviewed, tested, revised and re-validated by humans; the AI assists that work, it does not replace the judgement or the testing behind it. That is exactly the bar we ask of any contribution — whoever, or whatever, helped write it.

Code

  • AI-assisted code is as welcome as human-written code. We do not care how a change was produced — only whether it is correct, carefully tested, and fits the project. That bar is the same for everyone; there is no separate, lower one for either.

  • It has to be yours to give. Correct and tested is not enough — the code must also be legally clean: your own work or compatibly licensed, and offered under this project’s Apache-2.0 licence. Code copied from a proprietary or licence-incompatible source is not acceptable no matter how well it works, and regardless of whether a person or a machine produced it. By contributing you confirm you have the right to.

  • ITBH decides what to review and integrate. We may leave a contribution lying, or not act on it at all — there is no obligation to merge, or even to respond to, everything that arrives. Please do not read silence as anything more than limited attention.

  • Not to your taste? Fork it. That is exactly what the open licence is for — take it, run with it, make it yours. Good luck, and have fun with it.

Issues & bug reports

  • Reports are very welcome — they are how the project gets better, and using AI to help write a clear one is completely fine.

  • A human must stand behind every report — someone who understands what it is about, what the actual problem is, and can engage in a conversation about it.

  • Low-effort noise is ignored. Pseudo-findings, duplicate pile-ons, automated mass submissions, or a steady stream of unreviewed AI-generated reports will be ignored from that source onward.

Security reports go elsewhere

A suspected vulnerability does not belong in a public issue. Report it privately — GitHub’s "Report a vulnerability" form on the repository, or support@itbh.at with "Wusel Security" in the subject. Scope, what counts as out of scope, and the response times you can expect are in SECURITY.md in the repository root.

In short

Behave decently and genuinely want to help move Wusel forward, and you are welcome here. We want to make it better; we just will not be buried in noise.

What CI will run on your change

Four workflows under .github/workflows/. All of them go through mise, so CI runs the same pinned toolchain and the same mise run … tasks as a local checkout — there is no separate CI script to keep in sync.

Workflow Trigger What it does

CI (ci.yml)

every push to main and every pull request

Formatting, licence headers, clippy (-D warnings), check, the native test suite, and a Linux build of the FUSE frontend. The real-mount e2e is not run here (it needs a privileged /dev/fuse); CI only proves the frontend builds.

E2E (e2e.yml)

nightly, plus manual dispatch

The real-Nextcloud end-to-end run above, across the three newest maintained Nextcloud majors. Which those are is discovered from Docker Hub at run time, not written into the workflow, so a new Nextcloud release joins the matrix on its own. Only the newest is binding: the older two are run and reported, but a failure there does not turn the workflow red — a red build has to mean "we are broken", not "an old server is". Gated on the code or one of the image digests having changed since the last successful run, so a docs-only day costs nothing while a Nextcloud patch release re-arms the run.

Docs (pages.yml)

every push to main and every pull request

Builds this Antora site; pushes to main also publish it to GitHub Pages at itbh-at.github.io/wusel. Pull requests build only, as validation.

Release (release.yml)

a v* tag

Builds the packages for x86_64 and aarch64 and attaches them to a GitHub Release. See Packages.

Before pushing, mise run fmt-check, mise run clippy, mise run check and mise run test reproduce the CI job locally — see Set up a development environment.

If you touch a documentation diagram

The diagrams under documentation/diagrams/*.d2 are rendered to committed SVGs, and the docs build embeds those — it never runs d2, which is why the Pages workflow installs nothing but antora. The workflow after editing one:

mise run docs-diagrams        # re-render, then commit the changed SVGs

Forgetting that step used to be invisible: the site would build green and ship a picture that no longer matched the page around it. It is now caught, and without adding a d2 dependency to the build — mise run docs-diagrams records the hash of every source in diagrams/rendered.sha256, and documentation/check-diagrams.sh compares them. The docs build calls it (refusing an official build, warning in watch mode), so CI does too.

Sources beginning with an underscore are shared partials imported with …​@name, not diagrams — they are not rendered, but they are hashed, since a change to _steps.d2 invalidates every diagram that imports it.