Files
poli0981andClaude Opus 5.5 dcfe5c6b7c docs: maintenance mode
From 1.3.0 Hash Tool is in maintenance mode. What it accepts is written down once, in CONTRIBUTING.md ("Project
status"): security fixes (high/critical vulnerabilities in .NET or a dependency get a prompt release), dependency and
.NET updates, bug and UI/UX fixes, accessibility, translation fixes, and hash algorithms on real demand; no new
features unless truly necessary.

- README: maintenance, Qodana and .NET 10 LTS badges and a "Project status" section.
- CONTRIBUTING: the policy, the issue forms, and the hash algorithm candidates (BLAKE2b-512, SHA3-256/512, CRC-32C)
  with what each would take; ARCHITECTURE: a checklist for adding an algorithm.
- Issue forms: the feature request form is replaced by "Hash algorithm request" and "Translation problem"; feature
  ideas go to Discussions (Ideas). The accessibility form gives the email address for people who cannot use GitHub.
- Pull request template: the kinds of change that are accepted.
- SECURITY: 1.3.x supported, the security commitment during maintenance, Qodana among the checks.
- CLAUDE.md: the project status for agents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:20:51 +07:00

5.7 KiB

CLAUDE.md

Guidance for AI coding agents working in this repository. Human contributors: see CONTRIBUTING.md.

Project

Hash Tool — Avalonia 12 / .NET 10 desktop app (src/HashTool.App, executable CheckHash) plus the hashtool CLI (src/HashTool.Cli, NativeAOT), both built on src/HashTool.Core. Maintainer: poli0981 (GitHub). The maintainer writes in Vietnamese; reply in Vietnamese unless asked otherwise. Code, comments, commits and docs are English.

Read docs/ARCHITECTURE.md before larger changes and docs/RELEASING.md before touching packaging or the Release workflow.

Project status: maintenance mode since 1.3.0 (CONTRIBUTING.md, "Project status"). Accepted: security fixes (high/critical CVEs in .NET or dependencies get a prompt release), dependency and .NET updates, bug and UI/UX fixes, accessibility, translation fixes, adding or removing hash algorithms on real demand. Do not add features unless the maintainer explicitly asks; propose them instead.

Commands

dotnet build HashTool.slnx -warnaserror                 # CI treats warnings (incl. NuGet audit, analyzers) as errors
dotnet test --solution HashTool.slnx                    # Microsoft.Testing.Platform (global.json); not VSTest
dotnet format HashTool.slnx --verify-no-changes         # CI-enforced
python -I eng/loc.py check                              # translations: keys, placeholders, whitespace, wiring
dotnet src/HashTool.App/bin/Debug/net10.0/CheckHash.dll --smoke-test   # headless end-to-end check

Run the app or smoke test with HASHTOOL_DATA_DIR pointing at a scratch folder so the user's real settings (%LOCALAPPDATA%\HashTool) are never touched. Chain build/test/format/commit with &&, not ;.

Rules that are easy to break

  • Velopack/update invariants (docs/RELEASING.md): pack id HashTool, channels win/osx (+ osx-x64, linux), main exe CheckHash(.exe), macOS bundle id com.HashTool.HashTool (build/macos/Info.plist), no --packTitle on Windows, tags without v, settings path. Changing any of these strands 1.x users.
  • Never run a built HashTool-*-Setup.exe/.pkg on the maintainer's machine; test updates with portable builds in a scratch folder (the Release workflow's upgrade gate does this in CI).
  • Every UI string goes through Localization[Key] / L["Key"] and must exist in all 67 resx files; add keys with eng/loc.py set (JSON {culture: {key: value}}, "neutral" = English). App.Tests fail on missing, unused or mismatched keys. Keep "Hash Tool" untranslated inside sentences.
  • Accessibility (ACCESSIBILITY.md): every focusable control needs a translated name — AutomationProperties.Name on icon buttons and on buttons whose content is a panel (Avalonia announces the panel's type name otherwise); rows of lists get controls:RowTabNavigation.IsEnabled, buttons that swap places controls:FocusHandOff.Target; palette text colours ≥ 4.5:1, icon colours ≥ 3:1. AccessibilityTests enforce this; the UI Automation tree of a running app is the real check (Windows PowerShell 5.1 + UIAutomationClient).
  • Core is UI-free and AOT/trim compatible: no reflection-based JSON (use the source-generated contexts), keep ConfigureAwait(false) (Meziantou MA0004 is on for Core and CLI, off for App/tests).
  • Culture: use invariant formatting for logs, file names and machine-readable output; the UI uses the selected culture.
  • CRC32 is big-endian (standard); HashMatcher accepts the 1.1 little-endian form as LegacyByteOrderMatch.
  • Checksum entries must go through ChecksumEntry.ResolvePath (rejects UNC/device paths).
  • GitHub Actions: pin every action to a full commit SHA with a version comment, persist-credentials: false, per-job minimal permissions, no ${{ }} inside run: (pass through env:). zizmor and actionlint run in the Security workflow; ci-ok is the single required check.
  • Don't embed C# or regex text containing backslashes in Python/bash heredocs — the escapes get mangled. Edit such files with the editor tools.
  • .NET tools (vpk, nuget-license, CycloneDX, dotnet-sonarscanner, dotnet-coverage) live in .config/dotnet-tools.json; Dependabot doesn't read a root dotnet-tools.json. vpk and the Velopack package move together.

Workflows

  • ci.yml — build/test on Windows, macOS, Linux; coverage gate (Core ≥ 80%); smoke test; format; translation check.
  • security.yml — vulnerable packages, licences (eng/allowed-licenses.json), gitleaks, actionlint, zizmor.
  • release.yml — manual (workflow_dispatch, version + publish) with an upgrade gate from 1.1.3; dry run on PRs that touch release files. Discord notifications use the maintainer's poli0981/.github reusable workflows, pinned by SHA.
  • sonarcloud.yml — SonarCloud CI analysis (Automatic Analysis is off; project poli0981_HashTool): scanner build, Cobertura coverage from the tests and the smoke test (dotnet-coverage), "Sonar way" gate on new code. Skipped when SONAR_TOKEN isn't available (forks, Dependabot). Issues and hotspots can't be resolved from here; fix them in code.
  • codeql.yml — CodeQL advanced setup, mirroring default setup (actions, csharp, python; build mode none; default suite; /language: categories) but also analysing Dependabot pull requests. The Analyze (…) job names are required checks. Default setup must stay off: while it is on, it rejects uploads from workflows.
  • qodana.yml — JetBrains Qodana for .NET (Ultimate licence, qodana-dotnet in native mode, settings in qodana.yaml): results in Qodana Cloud, as annotations and a pull request comment, and in the qodana-report artifact (gh run download <run> -n qodana-report, then read qodana.sarif.json). Skipped when QODANA_TOKEN isn't available (forks, Dependabot); not a required check.