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

Live Unraid smoke scripts remain operator-controlled qualification tools for isolated test systems; weekly scheduled validation is fixture-only.

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