Files
MarkdownViewr.Windows/CONTRIBUTING.md
T
James MaesandCodex ce9afc6237 fix(ci): isolate casing analysis from competing rule lookups
Refs #5. Preserve every configured rule and fail closed; verify both partitions with negative fixtures. All 13 files and a bounded 20-case race probe pass locally.

Co-Authored-By: Codex (GPT-6) <noreply@openai.com>
Signed-off-by: James Maes <jmaes@dmdbrands.com>
2026-10-10 21:18:55 -05:00

6.8 KiB

Contributing to MarkdownViewr

Thanks for helping. This project follows the KofTwentyTwo standards; this page is the short version of what they ask of a contribution.

Before you start

For anything beyond a small fix, open an issue first so the approach can be agreed before you invest time. Questions and proposals are welcome in Issues.

Setup

Prerequisites: Windows 10 1809 or later, the .NET 10 SDK (global.json pins the feature band), and optionally Visual Studio 2026 or Rider. The workstation setup installs everything, including the git hooks' tools. The commands below are exactly what CI runs; run them before pushing.

dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --locked-mode
dotnet build MarkdownViewr.Windows.slnx -p:Platform=x64 -warnaserror

# Unit tests, then the 100% line-coverage gate over every measured assembly
dotnet test MarkdownViewr.Windows.slnx -p:Platform=x64 --no-build --filter "FullyQualifiedName!~UiTests" --settings coverage.runsettings --collect:"XPlat Code Coverage" --results-directory TestResults
./build/Assert-Coverage.ps1 -ResultsDirectory TestResults

# End-to-end UI tests: FlaUI launches the app (needs an interactive desktop)
dotnet test tests/MarkdownViewr.Windows.UiTests

# Style gate (Kingsrook layout, analyzers, naming)
dotnet format MarkdownViewr.Windows.slnx --verify-no-changes --severity warn --no-restore

# PowerShell tooling gate (install PSScriptAnalyzer 1.25.0 once)
Import-Module PSScriptAnalyzer -RequiredVersion 1.25.0
Invoke-ScriptAnalyzer -Path build -Recurse -Settings ./PSScriptAnalyzerSettings.psd1 -EnableExit
Import-Module Pester -RequiredVersion 5.7.1
Invoke-Pester -Path build/Assert-Coverage.Tests.ps1 -CI

dotnet format (without --verify-no-changes) fixes layout, var use, usings, and line endings. Two Kingsrook rules it cannot apply are checked in review: three blank lines between members, and a header comment on every type and method (Rider and ReSharper apply the blank lines from .editorconfig). Changing a package version means updating Directory.Packages.props and committing the regenerated packages.lock.json files (dotnet restore MarkdownViewr.Windows.slnx -p:Platform=x64 --force-evaluate).

Install the git hooks once per clone (the hook configuration comes from KofTwentyTwo/standards):

pre-commit install --hook-type pre-commit --hook-type commit-msg

Workflow

  1. Branch from main with a short-lived topic branch named <type>/<short-description>, for example feat/export or fix/42-splash-never-dismisses.
  2. Commit with Conventional Commits (feat: ..., fix(settings): ...). Every commit is signed and signed off: git commit -S -s (see Sign-off below).
  3. Open a pull request against main. Its title must itself be a Conventional Commit header: pull requests are squash-merged, so the title becomes the commit message on main.
  4. Every required check must pass, and every review thread must be resolved, before the pull request merges.

What makes a contribution acceptable

  • The build has zero warnings, and the format gate is clean.
  • New behavior has tests; a bug fix has a test that fails without the fix.
  • Line coverage of MarkdownViewr.Windows.Core stays at 100%. Logic goes in MarkdownViewr.Windows.Core; the WinUI project holds views and framework plumbing only (ADR-0001).
  • User-visible changes update the docs in the same pull request; attack-surface changes update the threat model.
  • No secrets, credentials, or personal data, ever.
  • New dependencies are justified in the pull request description.

Checks that gate a merge

Check What it verifies
pr / title The PR title is a Conventional Commit header
pr / dco Every commit is signed off
pr / dependency-review Added dependencies have no known vulnerabilities and an allowed license
security / secrets, security / sca, security / workflows No secrets, no vulnerable or malicious dependencies, safe workflows
codeql / analyze (csharp), codeql / analyze (actions) No high-severity static analysis findings
ci / build-test Locked restore, zero-warning build, unit tests, 100% coverage gate
ci / format dotnet format --verify-no-changes --severity warn
ci / ui-tests FlaUI end-to-end tests of the app
installed-updates Real stable/dev installers, upgrades, restart and published-output UI smoke
powershell, javascript Tool lint, setup/coverage boundary tests, review tests and dependency signatures
codeql / analyze (javascript-typescript) Static analysis of repository review tooling
review / automated (single maintainer) Current-commit automated review acknowledged by the configured human maintainer

Run npm ci --ignore-scripts, npm run lint and npm test for repository JavaScript. CI checks PSUseCorrectCasing alone, then all remaining rules, using the unchanged settings and failing on every finding or engine exception. This avoids the observed 1.25.0 command-metadata race; neither pass disables a required rule. Negative fixtures verify both partitions still report violations. For the same local workaround, supply -IncludeRule PSUseCorrectCasing and then -ExcludeRule PSUseCorrectCasing in two sequential Invoke-ScriptAnalyzer calls; evaluate findings from both. Run PSScriptAnalyzer with PSScriptAnalyzerSettings.psd1 and Pester against build/*.Tests.ps1. New owners follow repository setup.

Sign-off (Developer Certificate of Origin)

By signing off a commit you certify the Developer Certificate of Origin 1.1: that you wrote the change, or otherwise have the right to submit it under the project's license. git commit -s appends the sign-off:

Signed-off-by: Your Name <your.email@example.com>

The name and email must match the commit author. To add missing sign-offs to a branch, run git rebase --signoff main and force-push the branch.

AI-assisted contributions

AI coding tools are welcome. You remain the author: you must understand, test, and be able to explain every line you submit, and you sign it off as your own. Note substantial AI assistance in the pull request description. Include a Co-Authored-By trailer naming the model for significant AI contributions (K22-AGENT-40 / K22-AI-02).

License

By contributing, you agree that your contributions are licensed under the project's MIT License.