Skip to content

Latest commit

 

History

History
60 lines (36 loc) · 7.51 KB

CONTRIBUTING.md

File metadata and controls

60 lines (36 loc) · 7.51 KB

Contributing

简体中文

Markdown documents

New Markdown documents need an English file (topic.md or topic.en.md) and a Chinese file (topic.zh-CN.md) in the same directory. Keep only one English variant. Use these suffixes exactly. Delete both versions together.

Do not put dates in filenames, including 2026-11-12, 20261112, 2026-11, or 2026年11月12日. Put dates in the text or Git history. Dates in directory names are permitted.

The Chinese version needs at least 10 Chinese characters; the English version needs at least 5 English words. Code blocks, inline code, comments, and URLs do not count. These checks detect missing language content; reviewers must still check translation accuracy.

Existing violations are listed in tools/docs-policy-baseline.txt and may still be edited. Remove entries after fixing the documents. The list may only shrink. A renamed document or a new language counterpart is checked as a new document. New files have no directory exemptions, including vendor files and GitHub templates.

Local checks

Use Node.js 22. Install the hooks in each clone:

node tools/install-hooks.mjs

The hook checks the Git index, including partially staged files, and retains the existing Vue checks. To run checks yourself:

node tools/check-docs.mjs --staged
node tools/check-docs.mjs --all
node tools/check-docs.mjs --base origin/main
node --test tools/__tests__/docs-policy.test.mjs

--all checks HEAD; --base checks HEAD against the specified base. Both inspect Git objects, not unstaged edits. --all --write-baseline is a maintainer bootstrap command; CI rejects added exceptions once the policy is installed.

Branches and releases

  • main is the only development line. Create feature/<issue>-<summary> or fix/<issue>-<summary> from the latest main and merge it back through a pull request. Do not develop on release branches.
  • Pull request titles use type(scope): summary, for example fix(sequence): update state after step timeout. Pull requests are squash-merged, so the title becomes the commit message. Link work with Refs #123; QA closes the issue after verifying it in a later build.
  • Bugs found by QA follow the same path: a fix/ branch from main, a pull request back to main, then verification in the next daily build.
  • On the cut-off day the release owner creates release/A.B from main and tags vA.B.0-rc.N. A release branch only accepts backports of fixes that are already merged into main: add the backport-to-release/A.B label to the original pull request and a bot opens the cherry-pick pull request. Patch releases vA.B.C are tagged on the release branch.
  • Daily builds use the version A.B.0-dev.<yyyymmdd>. A and B are set by the product manager; C only changes for patch releases on a release branch.

Community packages

The community-package workflow builds three community installers: an EXE executable installer for Windows x64, a DEB Debian package for Linux x64, and a DMG disk image for macOS ARM64. They include OpenTest, the business plugins listed in default-plugins.json (currently fft-tools) from crysound/OpenTest-Plugins, and the SonoDAQ device plugin, but not the other plugins from the website package. Device plugins are bundled under backend/native/plugins/devices in the application resources. Windows retains test mode and uses the backend defaults without an explicit cloud.license.url; Linux and macOS use production license mode with the formal license service and separate generated configurations. There is no separate test server. Automatic updates are disabled. Windows is unsigned; macOS retains its multilingual license agreement and has only ad hoc signatures, without developer signing or Apple notarization. On first launch, choose Open Anyway in Privacy & Security. The SonoDAQ device plugin requires macOS 26 or later.

Desktop configuration owns the password-page URL independently of the native test / production license mode. Source runs and all platform installers, including Windows community packages, default to https://www.opentest.com/account/#change-password. The only developer override is CASDOOR_CHANGE_PASSWORD_URL: put it in the Git-ignored .local/runtime.env for local use, or inject it into the final CI packaging step. Quote URLs containing # in .env files (for example, "https://accounts.example/account/#change-password") to preserve the page fragment. Real test URLs are not committed to Git, and the frontend has no separate password-page environment variable.

Packaging writes the resolved URL into the bundled desktop field auth.changePasswordUrl. This is generated delivery data; manually edited local JSON and packaging modes do not override the URL. Installed applications read the bundled result and ignore the user's environment variable. Overrides must be HTTPS URLs without embedded credentials. An unset or blank value selects the official default; invalid values report a configuration error. Standalone browser builds without desktop configuration hide the entry.

The client opens the page in the system browser. The website manages the browser session; this entry does not synchronize client and website sessions. Deployments using another account service must supply its matching password page through the same override.

Each push to main publishes a daily prerelease A.B.C-dev.<yyyymmdd>; later builds on the same Beijing day add .2, .3 and so on. Pushing vA.B.C-rc.N or vA.B.C publishes a release candidate or release. First create the same tag in OpenTest-Plugins: a missing tag fails the build instead of falling back to main. Daily builds, pull requests, and manual runs use the plugin repository's main; manual runs cannot select an arbitrary plugin revision. Tag runs require the matching plugin tag. All three platforms check out the same resolved commit directly and verify it again, so a moving branch cannot change the build inputs. After every build and installation check succeeds, one publishing job uploads three installers and their SHA-256 checksum files before making the release public.

Pull requests targeting main trigger all three builds and installation checks, without publishing, when they change .github/workflows/community-package.yml, default-plugins.json, packaging.config.json, the packaging scripts listed in the workflow, tools/__tests__/**, tools/ci/**, or tools/publish-community-build.cjs. The workflow uses --edition community and does not trigger for unrelated application, SDK, vendor, manifest, or lockfile changes. package.json keeps the plain A.B.C used for plugin compatibility; the full version is passed to node tools/package.mjs --version.

GitHub enforcement

main and release/** require pull requests. Merging needs approvals from two members of @crysound/opentest (the author's own approval does not count), all review conversations resolved, and the required checks passing, including docs-policy. On main, CodeQL also blocks pull requests that introduce high-severity alerts. Force pushes and branch deletion are disabled. Policy files and workflows additionally require review by their CODEOWNERS.

CI runs the docs checker from the target branch against the proposed merge tree, without executing pull-request scripts. Each protected release branch carries the workflow and its own initial legacy list. Create future release branches from a branch that already contains the policy. Local hooks can be skipped; GitHub rules enforce merging. Repository administrators can still change repository settings.