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>
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, channelswin/osx(+osx-x64,linux), main exeCheckHash(.exe), macOS bundle idcom.HashTool.HashTool(build/macos/Info.plist), no--packTitleon Windows, tags withoutv, settings path. Changing any of these strands 1.x users. - Never run a built
HashTool-*-Setup.exe/.pkgon 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 witheng/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.Nameon icon buttons and on buttons whose content is a panel (Avalonia announces the panel's type name otherwise); rows of lists getcontrols:RowTabNavigation.IsEnabled, buttons that swap placescontrols:FocusHandOff.Target; palette text colours ≥ 4.5:1, icon colours ≥ 3:1.AccessibilityTestsenforce 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);
HashMatcheraccepts the 1.1 little-endian form asLegacyByteOrderMatch. - 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 minimalpermissions, no${{ }}insiderun:(pass throughenv:). zizmor and actionlint run in the Security workflow;ci-okis 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 rootdotnet-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'spoli0981/.githubreusable workflows, pinned by SHA.sonarcloud.yml— SonarCloud CI analysis (Automatic Analysis is off; projectpoli0981_HashTool): scanner build, Cobertura coverage from the tests and the smoke test (dotnet-coverage), "Sonar way" gate on new code. Skipped whenSONAR_TOKENisn'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. TheAnalyze (…)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-dotnetin native mode, settings inqodana.yaml): results in Qodana Cloud, as annotations and a pull request comment, and in theqodana-reportartifact (gh run download <run> -n qodana-report, then readqodana.sarif.json). Skipped whenQODANA_TOKENisn't available (forks, Dependabot); not a required check.