Contributing¶
You can help with code, documentation, reproducible bug reports, or testing a proposed fix. Start with the repository that owns the behavior.
Choose how to help¶
- Report a problem: use the steps below to describe what happened and share relevant, redacted logs.
- Improve a guide: report a confusing instruction or submit a documentation correction.
- Help another user: join the community discussion.
- Support the DUMB maintainer: use GitHub Sponsors. Integrated applications have their own maintainer links in the service guides.
Report a problem¶
Include the DUMB image/version, relevant application version, what you expected, what happened, and the smallest steps that reproduce it. For UI issues, include the browser and a screenshot if useful.
Use logs exported through DUMB where possible. Review logs, configuration, screenshots, and URLs for credentials and personal information before attaching them. Do not upload a whole configuration directory or database to a public issue.
flowchart TD
A["Find the repository that owns the problem"] --> B["Write the smallest reproduction"]
B --> C["Add versions and redacted evidence"]
C --> D["Report the issue or propose a focused fix"]
D --> E["Check the result and describe remaining limits"]
Geek contribution guide: repositories, branches, development and validation
Choose a repository and branch¶
| Change | Repository | Normal pull request target |
|---|---|---|
| Backend API, service installation, process lifecycle, container image | DUMB | dev |
| Dashboard, onboarding UI, embedded proxy, browser behavior | dmbdb | dev |
| This documentation site | DUMB_docs | master |
DUMB's release branch is master; dmbdb's release branch is main. Normal fixes and features go to dev. Release work and approved hotfixes may target the release branch.
A change can span repositories. An API change may need a dashboard capability check and a docs update; a dashboard workflow change may need revised user instructions.
Develop and validate¶
Use the selected repository's devcontainer and checked-in instructions. For the backend, fork the repo, create a feature branch from dev, and run focused tests while iterating.
Before opening a backend pull request:
make format applies formatting; make verify checks metadata, the lockfile, formatting, lint, syntax, tests, and security. Run it in a disposable development environment rather than against a live media library.
For the dashboard, use the pinned package manager, a frozen lockfile installation, the relevant test scripts, and a production build. Embedded routing changes need the repository's browser checks as well.
For docs, use the repository README for the current build and validation commands. Check both release and development output when changing channel-specific content.
Service installer and updater regressions¶
DUMB includes a disposable previous-version-to-latest matrix. It gives each selected case fresh configuration, data, logs, mounts, and databases rather than downgrading an operator's installation.
From a Docker-capable development host:
Two workers are the default because source builds can be resource-intensive. To focus a run, pass REGRESSION_ARGS="--case <case-id>"; use --include-pending while qualifying a pending entry. --use-gh-auth-token uses the current GitHub CLI token without printing it.
The matrix is scripts/service_update_regression_matrix.json. Qualified entries run by default. Pending entries still need prior versions, dependency fixtures, or disposable credentials. Reports go to ignored .regression-reports/; the separate verified install cache is retained for reuse checks.
Submit a pull request¶
Describe the concrete problem, the resulting behavior, and how you tested it. Link related issues, include screenshots for UI changes, and update user docs when behavior changes. Keep unrelated cleanup separate.
Use Conventional Commit titles, for example:
fix(proxy): preserve embedded service WebSocket routingfeat(api): expose symlink comparison resultsdocs: clarify first-run provider setup
Distinguish automated checks from any manual or operational testing that remains. For dependency updates, inspect the changed versions and the affected runtime path as well as the build result.
For a larger feature, discuss the proposed behavior in an issue or the community before building it.