Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (143 loc) · 8.72 KB

CONTRIBUTING.md

File metadata and controls

180 lines (143 loc) · 8.72 KB
Raw

Contributing to winprint

Pull requests are welcome. This guide gets you from git clone to building, testing, and debugging winprint in VS Code on Windows, macOS, or Linux.

winprint started life as a Windows app. On Windows everything builds, runs, and debugs today. The cross-platform story (macOS/Linux) is in progress — see issue #64 and the matrix below for what works where right now.

Prerequisites

  1. .NET 10 SDK — the version is pinned by global.json. Get it from https://dotnet.microsoft.com/download/dotnet/10.0. Verify with dotnet --version.
  2. MAUI workload (only needed to build/run the WinPrint.Maui app). From the repo root, restore the workloads required by the MAUI project: 
    dotnet workload restore src/WinPrint.Maui/WinPrint.Maui.csproj
    On macOS the Mac Catalyst build additionally needs full Xcode (not just the Command Line Tools), and the version must match what the workload pins — currently Xcode 26.5 (the 26.5 Apple SDK). Install it, then: 
    sudo xcode-select -s /Applications/Xcode.app
sudo xcodebuild -license accept
    A mismatched Xcode fails with "requires the MacCatalyst 26.5 SDK"; Command Line Tools alone fail with "A valid Xcode installation was not found". You can also run the VS Code task restore-maui-workloads. A fresh .NET 10 SDK may report NETSDK1147 for a specific MAUI workload such as maui-tizen; that means the MAUI workload set has not been restored yet. On Windows, restart VS Code after installing the SDK or workload so the integrated terminal and extensions pick up the updated PATH.
  3. libgdiplus (macOS/Linux only) — the Windows System.Drawing measurement and the full test suite P/Invoke GDI+, which ships natively on Windows. On other platforms: 
    brew install mono-libgdiplus          # macOS
sudo apt-get install -y libgdiplus    # Debian/Ubuntu

Open in VS Code

git clone https://github.com/tig/winprint.git
cd winprint
code .

VS Code will prompt to install the recommended extensions (.vscode/extensions.json) — accept them:

  • C# Dev Kit (ms-dotnettools.csdevkit) + C# (ms-dotnettools.csharp) — Roslyn language service, build, and debug.
  • .NET MAUI (ms-dotnettools.dotnet-maui) — MAUI build/debug targets.
  • EditorConfig (editorconfig.editorconfig) — applies .editorconfig.

The solution is loaded automatically from WinPrint.slnx (dotnet.defaultSolution in .vscode/settings.json).

If starting WinPrint.Maui (Windows) shows Couldn't find a debug adapter descriptor for debug type 'maui', the .NET MAUI extension did not activate. In VS Code or VS Code Insiders, verify that C# Dev Kit, C#, and .NET MAUI are installed and enabled, then run Developer: Reload Window. If it still fails, check Output → C# Dev Kit and Output → .NET MAUI; the usual causes are dotnet not being on VS Code's PATH, a missing maui workload, or C# Dev Kit not being signed in/activated.

Build, test, debug

Tasks (Command Palette → Tasks: Run Task, or Ctrl/Cmd+Shift+B for the default)

Task What it does
build (default) Windows: full solution. macOS/Linux: WinPrint.Core only.
build-tui Builds WinPrint.TUI (wp).
build-solution Builds the whole WinPrint.slnx (needs the MAUI workload).
build-maui-windows Builds WinPrint.Maui for Windows (needs the MAUI workload).
restore-maui-workloads Restores the MAUI workloads required by WinPrint.Maui.
test Runs the WinPrint.Core.UnitTests suite.
publish-tui dotnet publish -c Release -f net10.0 of the wp command.

Or from a terminal:

dotnet build src/WinPrint.Core/WinPrint.Core.csproj                       # both TFMs
dotnet test  tests/WinPrint.Core.UnitTests/WinPrint.Core.UnitTests.csproj

Debug (Run and Debug panel — .vscode/launch.json)

Profile Notes
WinPrint.TUI Terminal.Gui front end and wp command.
WinPrint.Maui (Windows) Directly launches the unpackaged Windows MAUI EXE. Needs the MAUI workload.
WinPrint.Maui (Mac Catalyst) MAUI app on macOS. Needs the MAUI workload.

What builds/runs where today

Project Windows macOS / Linux
WinPrint.Core ✅ ✅ (net10.0)
WinPrint.Core.UnitTests ✅ ✅ cross-platform suite; some Windows/GDI+ tests are skipped or env-dependent (see CLAUDE.md)
WinPrint.TUI ✅ ✅ (net10.0)
WinPrint.Maui ✅ ✅ net10.0-maccatalyst builds with the MAUI workload + Xcode 26.5; the Windows head only builds on Windows. Runtime not yet verified (#64)

Before you push

CI (.github/workflows/ci.yml) runs a style gate that fails the build on any diff. Match it locally:

dotnet tool restore
dotnet jb cleanupcode WinPrint.slnx --profile="WinPrintCleanup" --exclude="**/*.xaml.cs"
dotnet format WinPrint.slnx
git diff --exit-code

The repo also enforces one top-level type per file (WPA0001) and no nested types (WPA0002) via analyzers. There's a Build.ps1 helper at the repo root for scripted builds.

Versioning

WinPrint uses GitVersion for automatic semantic versioning. You do not need to manually bump version numbers.

  • Version is derived from Git history (tags and branch names).
  • Just tag on main — GitVersion handles the rest.
  • Feature branches automatically get pre-release version suffixes.

Release process

Releases are fully automated via CI:

  1. Merge develop → main. (There is no release branch.)
  2. Create and push a version tag on the merge commit. The tag must be annotated (git tag -a) — a lightweight tag will not drive the release/versioning correctly: 
    git tag -a v3.0.0 -m "Release 3.0.0"
git push origin v3.0.0
  3. CI automatically:
    • Builds for Windows, macOS, and Linux
    • Signs the Windows binaries (Azure Trusted Signing via OIDC). macOS is not signed/notarized today — the APPLE_* secrets are not configured (#162) and the .app ships unsigned/ad-hoc.
    • Creates a GitHub Release with all assets
    • Produces winget and Homebrew-ready artifacts/templates

Signing secrets (for forks)

If you fork this repository and want to produce signed builds, configure the following repository secrets.

Windows signing works today (Azure Trusted Signing via GitHub OIDC — no client secret). See docs/code-signing.md:

Secret Description
AZURE_CLIENT_ID Azure app registration client ID for Trusted Signing OIDC
AZURE_TENANT_ID Azure tenant ID
AZURE_SUBSCRIPTION_ID Azure subscription containing the signing account
AZURE_SIGNING_ACCOUNT Azure Trusted Signing account name
AZURE_SIGNING_PROFILE Azure Trusted Signing certificate profile
AZURE_SIGNING_ENDPOINT Azure Trusted Signing endpoint

macOS signing is NOT configured on this repo (#162): the APPLE_* secrets below are not set, so the macOS .app currently ships unsigned/ad-hoc (Gatekeeper warns). The release workflow already supports these secrets — set them on a fork to enable Developer ID signing + notarization:

Secret Description
APPLE_CERTIFICATE_BASE64 Base64-encoded Apple Developer ID .p12 certificate
APPLE_CERTIFICATE_PASSWORD Password for the .p12 certificate
APPLE_ID Apple Developer account email
APPLE_APP_SPECIFIC_PASSWORD App-specific password for notarization
APPLE_TEAM_ID Apple Developer team ID
APPLE_SIGNING_IDENTITY Developer ID Application signing identity

Without these secrets, CI will still build successfully but the affected binaries will be unsigned.