Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
237 lines (179 loc) · 8.68 KB

CONTRIBUTING.md

File metadata and controls

237 lines (179 loc) · 8.68 KB
Raw

Contributing to SysManager

Thanks for wanting to help! SysManager is a small, solo-maintained project and every clean PR is welcome — bug fixes, docs, tests, new features, or even just a well-written bug report.

This document describes how to get set up, the conventions the codebase follows, and what to expect when you open a pull request.

Table of contents

Ways to contribute

  • 🐛 Report a bug — open an issue with the bug template. Crash logs, repro steps, and Windows version are gold.
  • 💡 Suggest a feature — open an issue with the feature template. Small, targeted suggestions land faster than big design proposals.
  • 🧪 Improve tests — more edge cases, more fixtures. The suite is the spec for this project.
  • 📚 Improve docs — typos, clearer wording, fresh screenshots, better examples. Doc-only PRs are merged fast.
  • 🛠 Fix a bug or implement a feature — see open issues. Please comment on the issue before starting significant work so we don't both build the same thing.

Development setup

Prerequisites

  • Windows 10 or later (WPF + Windows APIs won't build elsewhere).
  • .NET 10 SDK.
  • Git 2.40+.
  • A Windows account with admin rights (needed to test elevated features; the app itself runs fine unelevated for everything else).

Clone and build

git clone https://github.com/laurentiu021/SystemManager.git
cd SystemManager
# Build the app project directly — this is what CI does. A SysManager.sln also
# exists (SysManager/SysManager.sln) if you prefer the full solution in Visual Studio / Rider.
dotnet build SysManager/SysManager/SysManager.csproj -c Debug

Run the app

dotnet run --project SysManager/SysManager/SysManager.csproj

Run the tests (see Running tests for more)

dotnet test SysManager/SysManager.Tests/SysManager.Tests.csproj -c Release

Project layout

SysManager/
├── SysManager/                # main WPF app
│   ├── Data/                   # static data (ProcessDescriptions.json)
│   ├── Models/                # POCOs (no logic)
│   ├── Services/              # Windows / PowerShell / CLI wrappers
│   ├── ViewModels/            # MVVM, one per tab
│   ├── Views/                 # XAML + minimal code-behind
│   ├── Helpers/               # small utilities, converters
│   └── Resources/             # icons, generated assets
├── SysManager.Tests/          # xUnit unit tests
├── SysManager.IntegrationTests/ # integration tests (local only, not CI)
└── SysManager.UITests/        # FlaUI UI-automation tests

See ARCHITECTURE.md for the deeper tour.

Coding conventions

The codebase is small enough that the existing files are the best style guide. That said, a few explicit rules:

  • MVVM strict: business logic lives in view models and services, not in code-behind. Views are XAML with bindings; .xaml.cs should be empty or near-empty.
  • CommunityToolkit.Mvvm source generators ([ObservableProperty], [RelayCommand]) — use them. No manual INotifyPropertyChanged or ICommand boilerplate.
  • Services are testable: prefer constructor-injectable seams over statics. If a service must be static, keep it pure (HealthAnalyzer, EventExplainer).
  • No silent failures: catch exceptions close to the boundary (PowerShell, file I/O, network) and surface them as log lines or UI state. Never swallow.
  • 4 spaces, no tabs. Braces on their own line (standard .NET style).
  • var freely when the type is obvious from the right-hand side.
  • Async all the way down for anything that touches I/O.
  • AutomationId on every nav item and primary button so UI tests can find them.
  • Admin elevation is opt-in: never demand admin unless the feature genuinely requires it. Show a banner, never a modal.

XAML conventions

  • Resources in App.xaml for anything reused more than once.
  • Dark-gradient theme stays consistent; no hard-coded colours — use the existing brushes.
  • Accessibility: every interactive control has a label or AutomationProperties.Name.

Running tests

Unit tests run in parallel by default (parallelizeTestCollections: true). Tests that share state or touch OS resources are isolated via xUnit collection definitions in TestCollections.cs (each DisableParallelization = true), so file-system fixtures never collide. The integration suite runs sequentially.

Full run:

dotnet test SysManager/SysManager.Tests/SysManager.Tests.csproj -c Release
dotnet test SysManager/SysManager.IntegrationTests/SysManager.IntegrationTests.csproj -c Release
dotnet test SysManager/SysManager.UITests/SysManager.UITests.csproj -c Release

The integration tests touch the live system, so CI only compile-checks them — run them locally, not over SSH/Remote PowerShell. CI runs the unit tests as the merge gate and the UI-automation tests as a separate, non-blocking job (they need the interactive desktop a windows-latest runner provides).

Filter to one class while iterating (pass the project the class lives in — PingMonitorServiceTests is an integration test):

dotnet test SysManager/SysManager.IntegrationTests/SysManager.IntegrationTests.csproj --filter "FullyQualifiedName~PingMonitorServiceTests"

Generate a coverage report:

dotnet test SysManager/SysManager.Tests/SysManager.Tests.csproj -c Release --collect:"XPlat Code Coverage"

Every non-trivial PR should include at least one test. If you're unsure where it belongs, look at the closest existing *ServiceTests or *ViewModelTests file and match the pattern.

Commit messages

Keep them short and imperative. The first line is the headline (≤ 72 chars), then a blank line, then optional detail.

Good:

Add SHA256 verification to UpdateService

Downloads now compare the advertised hash against the local file and
refuse to install on mismatch. Covered by UpdateServiceHashTests.

Bad:

fixed stuff

Prefixes aren't required, but if you want a convention: fix:, feat:, docs:, test:, refactor:, ci: are all understood.

Pull request process

  1. Fork the repo and create a branch from main: git checkout -b feat/my-feature.
  2. Build and run the tests locally. PRs that don't build or break existing tests will be asked to fix that first.
  3. Add or update tests for your change.
  4. Update docs if the change is user-visible (README, CHANGELOG, ARCHITECTURE where relevant).
  5. Open the PR against main. Fill out the PR template honestly — if you didn't add tests, say why.
  6. CI must be green before review starts. On a Windows runner, CI builds the app, runs the unit-test project, compile-checks the integration-test project, and runs the UI-automation tests as a separate non-blocking job.
  7. Review and iterate. I try to respond within a few days. If a PR goes silent, ping me with a comment.
  8. Squash merge is the default. Your individual commits are preserved in the PR but the main history stays linear.

What makes a PR easy to merge

  • Focused on one thing.
  • Tests that fail before the fix and pass after.
  • No unrelated reformatting or style churn.
  • A clear "why" in the description (link the issue if there is one).

Reporting bugs

Open an issue with the Bug report template. The template asks for:

  • Which tab and which action.
  • What you expected vs. what happened.
  • Steps to reproduce (if deterministic).
  • SysManager version (from the About tab) and Windows build.
  • Logs, if possible: %LOCALAPPDATA%\SysManager\logs\.

The About tab has a "Copy environment info" button that dumps most of this in a format ready to paste.

Requesting features

Open an issue with the Feature request template. Tell me:

  • The problem you're trying to solve (not the solution you imagine).
  • Who else this would help.
  • Any constraints — admin required? offline? specific Windows version?

Small, focused requests beat big open-ended ones.

Security issues

Do not open a public issue for a security vulnerability. See SECURITY.md for how to report privately.

Thanks again — and welcome aboard!