Skip to content

development.md

Latest commit

 

History

History
83 lines (59 loc) · 2.46 KB

development.md

File metadata and controls

83 lines (59 loc) · 2.46 KB
Raw

Development guide

Prerequisites

  • Git
  • .NET 10 SDK 10.0.300 or a newer patch
  • Windows, macOS, or Linux for build and tests

global.json selects the .NET 10 10.0.3xx feature band and accepts its latest installed patch. CI installs the latest .NET 10 SDK.

Build and test

./scripts/verify.sh

The script performs a Release restore/build and test pass. Individual commands:

dotnet restore Blueprints.sln
dotnet build Blueprints.sln --configuration Release --no-restore
dotnet test Blueprints.Tests/Blueprints.Tests.csproj --configuration Release --no-build

Run the app:

./scripts/run-app.sh

Or:

dotnet run --project Blueprints.App/Blueprints.App.csproj

Platform notes

  • Windows is the most mature runtime target and uses DPAPI for private-key protection.
  • macOS and Linux use the local AES-GCM protector.
  • On Linux, Avalonia may require X11/XWayland. scripts/diagnose-linux-display.sh explains missing display state.
  • Tests create isolated workspaces and must not read or write real application data.

Repository workflow

  • develop is the integration/default branch.
  • main contains promoted release-ready states.
  • Branch from develop using feature/<slug>, fix/<slug>, docs/<slug>, or chore/<slug>.
  • Open pull requests into develop.
  • Promotion pull requests move verified changes from develop to main.
  • Releases are tagged from main.

Code organization

  • Keep the domain free of UI and provider dependencies.
  • Put canonical persistence rules in Storage.
  • Put key handling and signatures in Security.
  • Put exchange/sync behavior in Collaboration.
  • Keep hosted integrations outside signed project truth.
  • Prefer immutable records for persisted documents.
  • Add a regression test before or with every bug fix.

Adding a persisted field

  1. Decide whether it is signed project truth or local-only state.
  2. Update the relevant record.
  3. define compatibility behavior for older files.
  4. update canonical serialization or workspace tests.
  5. update workspace format.
  6. add migration logic when schema versions begin diverging.

Troubleshooting

If SDK selection fails:

dotnet --list-sdks
dotnet --version

Install .NET 10 SDK 10.0.300 or a newer patch in the same feature band. Do not edit a parent-directory global.json; this repository has its own pin.

If restore is slow on first use, let NuGet finish populating its cache. Subsequent builds should be much faster.