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>
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
- Branch from
mainwith a short-lived topic branch named<type>/<short-description>, for examplefeat/exportorfix/42-splash-never-dismisses. - Commit with Conventional Commits
(
feat: ...,fix(settings): ...). Every commit is signed and signed off:git commit -S -s(see Sign-off below). - 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 onmain. - 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.Corestays at 100%. Logic goes inMarkdownViewr.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.