Contributing Testing and Releases

Contributing, Testing, and Releases

Development happens on dev; main is the stable release branch. Normal pull requests should branch from and target dev.

Before starting

1. Search existing issues and discussions.
2. Use the bug, feature, support, or translation issue form.
3. Keep one focused problem per pull request.
4. Read current architecture/support contracts for the affected surface.

Local setup

Required baseline tools include Node.js 20+, PHP, Bash, and shellcheck. Clone/fork the repository, create a branch from dev, install dependencies as documented, and enable repository hooks:

bash scripts/install_git_hooks.sh

Shared validation

Run the complete entry point:

bash scripts/run_ci_suite.sh

Focused lanes include lint, tests, workflow-tests, guards, workflow-guards, docs-guards, fixture-browser, browser-smoke, and theme-matrix. Use --help for the current list.

Runtime rendering/shared UI changes should run deterministic browser fixtures:

bash scripts/run_ci_suite.sh --lane fixture-browser

Hydration, rendering, reconciliation, observer, or large-data changes should also run:

npm run test:runtime-performance

Tracked validation does not connect to a live Unraid server and does not accept live target URLs or credentials. Browser smoke, theme, responsive, release, back-merge, and weekly scheduled validation use isolated local fixtures.

The Docker API fixture matrix includes compatible full and targeted reads, an absent legacy API, denied introspection, limited and partial shapes, permission denial, rate limiting, service unavailability, schema drift, and a future native host. Use the prerelease qualification checklist for any additional manual observation on a disposable test system; it is not a secret-backed CI requirement.

Scheduled and upstream monitoring

• Cross-browser fixtures run every Monday in Chromium, Firefox, and WebKit.
• The Unraid compatibility monitor checks public OS, PHP, webGUI, plugin-manager, API, and Community Applications contracts daily.
• CodeQL, OpenSSF Scorecard, and the generated-SBOM OSV scan run weekly.
• The scheduled-workflow watchdog opens or updates one recovery issue when an expected successful run is missing, failed, or stale, and closes it after recovery.

Compatibility baseline updates are always human-reviewed. Scheduled jobs must stay deterministic and isolated; do not add live-Unraid targets or secrets to make a monitor pass.

Pull request expectations

• Explain what changed, why, impact, and root cause for fixes.
• Add/update focused tests.
• Include desktop/mobile and light/dark screenshots for UI changes.
• Update user docs, troubleshooting, current-state metadata, screenshots, release notes, and translations when behavior changes.
• Preserve compatibility unless an intentional deprecation is documented.
• Do not commit secrets, private URLs, support bundles, or machine-specific configuration.

Coding standards

• Follow existing structure and naming.
• Prefer small composable functions and shared modules.
• Avoid global CSS selectors and new inline event handlers.
• Escape user/persisted content before HTML insertion.
• Use shared request, storage, UI, localization, theme, and lifecycle contracts.
• Ensure repeated Unraid navigation does not duplicate listeners, observers, timers, or requests.

Versioning and packaging

Versions use YYYY.MM.DD.UU, with a zero-padded update counter. The package builder selects versions and generates checksums; contributors should not hand-edit generated hashes.

Runtime changes require curated release notes, relevant full validation, a dev package build, release/install guards, archive review, commit/push to dev, and remote publication verification under maintainer workflow.

Stable releases are prepared from main and publish package/checksum assets, attestations, and SBOM evidence. See Security and Package Trust.

Documentation changes

Keep wiki language user-oriented, link rapidly changing internal contracts to source docs, use standardized screenshot placeholders, and avoid embedding version-specific claims unless the page is explicitly historical. Validate all internal links before publishing.

Authoritative contributor guide: CONTRIBUTING.md