Skip to content

Maintenance

Jump to bottom
BilgeGates edited this page May 23, 2026 · 1 revision

Maintenance

This page describes how to report defects, request features, and contribute to ChessVision against the v5.5.3 stable release on master.

Reporting Bugs

Bug reports are filed as GitHub issues. Two templates are available from the New Issue picker on the repository:

  • Bug Report — A structured form (bug_report.yml). Use this by default. It collects environment details, reproduction steps, expected and actual behavior, and screenshots in clearly delimited fields.
  • Bug Report (Quick) — A minimal plain-Markdown alternative (bug_report.md). Use this when the structured form is not appropriate.

Every new bug should include:

  1. A one-sentence summary of the defect.
  2. Numbered reproduction steps that begin from a clean session.
  3. The expected behavior.
  4. The actual behavior, with error messages, stack traces, or console output where applicable.
  5. The browser and version, the operating system, and whether the issue reproduces on desktop, mobile, or both.
  6. The ChessVision version or commit hash. v5.5.3 corresponds to the most recent release tag on master.

Bugs that involve the export pipeline should additionally include the export preset, the requested board size, and whether the canvas was disposed (the canvas.width = 0 invariant after every blob generation must hold).

Severity and Triage

Bugs are triaged into three classes:

  • Crash-class. Canvas out-of-memory, navigation crashes, regressions in the export pipeline. These are prioritized for backport to master as a v5.5.x patch.
  • Functional. Defects that do not crash or destroy data. Routine fixes ship in the next minor or patch. Non-routine fixes may be deferred to the next major.
  • Cosmetic. Visual polish and non-blocking layout issues. Generally deferred to the next major release unless trivial.

All open issues carry an area:*, priority:*, and effort:* label.

Label family Values Meaning
area:* area:export, area:ci, area:auth Subsystem affected
priority:* priority:high, priority:low Triage priority
effort:* effort:small, effort:large Expected effort

Open issues are tracked on the ChessVision project board.

Requesting Features

Feature requests are filed through the Feature Request template (feature_request.yml) on the New Issue picker. Each request should describe:

  1. The problem the feature solves, framed in terms of a user task.
  2. The proposed behavior.
  3. Alternatives that have been considered.
  4. Whether the request applies to the v5.x stable line or to the next major release.

Feature requests against the v5.x line are accepted only when they fall within the maintenance policy stated below. New user-facing features generally land on develop and ship in the next major release.

Maintenance Policy (v5.x)

In scope for v5.5.x patch releases

  • Security patches (dependency CVEs, SAST findings).
  • Dependabot dependency bumps for direct dependencies, reviewed and merged in batches.
  • Documentation corrections, typo fixes, and link-rot repair.
  • CI and release-pipeline fixes.
  • Build-configuration fixes that do not alter user-facing behavior.

Not in scope for v5.5.x patch releases

  • New user-facing features.
  • Schema or API changes.
  • Breaking changes to localStorage keys, FEN history format, or settings shape.
  • TypeScript migration of additional files.
  • Performance refactors that change observable behavior.

Branch model

  • master — stable. Receives only the changes described above.
  • develop — active development. The next major release accumulates here.
  • Feature branches target develop. Patch branches against the v5.x line target master directly and must remain within the maintenance scope.

Contributing

The contribution workflow is documented in CONTRIBUTING.md on master. The summary:

  1. Fork the repository and check out the appropriate branch (develop for new features; master only for v5.x patches that fall within the maintenance scope).

  2. Run pnpm install.

  3. Create a feature branch with a Conventional Commits-compatible name (for example, fix/export-canvas-oom or chore/deps-bump).

  4. Make changes. Before submitting, run all three quality gates:

    pnpm test
pnpm lint
pnpm format:check

  5. Commit using Conventional Commits. Commitlint enforces the format on commit-msg.

  6. Open a pull request against the appropriate base branch. The pull-request template will populate.

  7. Address review comments. Once approved, the PR is merged by a maintainer.

Security

Security-sensitive reports must not be filed as public GitHub issues. The supported disclosure channel is documented in SECURITY.md on master.

The v5.x line treats the following as security invariants:

  • safeJSONParse is mandatory for every untrusted string-to-object conversion. Direct JSON.parse on external data is forbidden.
  • sanitizeFileName, sanitizeInput, and sanitizeHexColor are applied at system boundaries before rendering untrusted strings to the DOM or using them in file names.
  • MAX_FEN_LENGTH = 93 is enforced before any parse attempt; unbounded string processing is not permitted.
  • react/jsx-no-target-blank is configured as an ESLint error; outbound links must carry rel="noopener noreferrer".

References

Clone this wiki locally