Thank you for your interest in contributing! Bug reports, fixes, newly surfaced protocol fields and documentation improvements are all welcome.
Before you start on a larger change, please open an issue so we can agree on the approach. Questions go to Discussions, and security problems go through SECURITY.md, never a public issue.
Everyone taking part is expected to follow the Code of Conduct.
- .NET 10 SDK.
- The .NET 8 runtime. Each test project also runs on a
net8.0host, which is how thenetstandard2.0build of the libraries gets tested. Without it, run-f net10.0locally and let CI cover the other half. - Git.
- A Rust server and the Rust+ app, only if you want to check a change live. The test suite runs against an in-process mock server and needs neither.
git clone https://github.com/HandyS11/RustPlusApi.git
cd RustPlusApi
dotnet tool restore # ReSharper formatter, ReportGenerator, Stryker
dotnet build # also points git at the committed hooks in .githooks/
dotnet test RustPlusApi.slnThe first dotnet build runs git config core.hooksPath .githooks, which installs the
pre-push hook. There is nothing else to set up.
| Path | What's there |
|---|---|
src/ |
The six packages: RustPlusApi, .Camera, .Fcm, .Fcm.Registration and the two *.Extensions.DependencyInjection |
tests/ |
Unit and integration tests per package, and RustPlusApi.MockServer, the in-process Rust+ server the integration tests share |
samples/ |
Console apps for the client, camera, FCM listener and credential registration |
docs/ |
The DocFX site: guides in articles/, contributor docs in development/ |
tools/ |
update-proto (regenerates the protocol from the Rust server) and coverage (the local coverage gate) |
dotnet build # warnings are errors, see below
dotnet test RustPlusApi.sln # every test project, on both hosts (net8.0 and net10.0)
# One test class or method (still both hosts):
dotnet test RustPlusApi.sln --filter "FullyQualifiedName~ClassName.MethodName"
# One host only:
dotnet test RustPlusApi.sln -f net8.0 # the netstandard2.0 build
dotnet test RustPlusApi.sln -f net10.0 # the net10.0 build
# Coverage, with a per-class report of anything below 100% and the CI gate:
tools/coverage/report.shdocs/development/testing.md explains the test projects, the coverage
exclusions and mutation testing in detail. Read it before you change tests.
-
Warnings are errors. The build runs with
TreatWarningsAsErrorsand thelatest-allanalyzer set, plus Roslynator, SonarAnalyzer, the VS threading analyzers and the IDE code-style rules. Fix what they report. If a suppression is truly needed, put the reason in a comment next to it. -
Two targets. Every library builds for
netstandard2.0andnet10.0, so it runs on .NET Framework 4.6.2 and later as well as modern .NET. Missing APIs on the old target are bridged inPolyfills/or with#if NET10_0_OR_GREATER. Each such fork needs a test that runs on both targets and asserts the same result. -
Coverage. New code is expected at 100% line and branch coverage, and CI gates the merged total at 95% line and 90% branch. Code that can only run against the real network (a TLS handshake, a live Steam login) can be marked
[ExcludeFromCodeCoverage]with a justification comment, and must be added to the exclusion list intesting.md. Test the logic behind it throughinternalseams instead. -
Mutation testing. A weekly Stryker run checks that tests actually pin behavior. Run it for one package from its unit-test directory:
cd tests/RustPlusApi.Fcm.UnitTests dotnet stryker --config-file stryker-config.json --project RustPlusApi.Fcm.csprojStryker can't mutate the core
RustPlusApipackage, so pin core behavior with exact-assertion unit tests. -
Package versions live in
Directory.Packages.props. A.csprojreferences a package without a version. -
Don't bump versions. Local builds are always
1.0.0. CD takes the real version from the release tag.
Formatting and member order come from the ReSharper command-line formatter, configured by
.editorconfig and the ReformatAndReorder profile in RustPlusApi.sln.DotSettings:
dotnet jb cleanupcode RustPlusApi.sln --profile="ReformatAndReorder"The pre-push hook runs it on the files you're pushing and rejects the push if it changes
anything, leaving the fixed files in your working tree. Commit them and push again. See
docs/development/formatting.md.
src/RustPlusApi/Protobuf/RustPlusContracts.proto is authoritative: it is regenerated by decompiling
the Rust dedicated server (see tools/update-proto), and the C#
contracts are generated from it at compile time. Don't edit generated code.
Each month the ProtoRefresh workflow compares the proto with the latest server and opens a
proto-drift issue when they differ. To surface a new field:
- Copy the field from the drift report into
RustPlusContracts.proto. - Add a nullable property to the public model in
src/RustPlusApi/Data/. A field the server leaves out should map tonull, not to0orfalse, so read it through the generatedShouldSerialize<Field>()method. - Map it in
src/RustPlusApi/Extensions/, with tests for both a present and an absent value. - Add it to the matching article in
docs/articles/.
- Create a branch from
develop, in a fork if you don't have write access. - Make the change, with tests.
- Make sure
dotnet buildanddotnet test RustPlusApi.slnpass, and that the formatter has nothing to change. - Open the pull request against
developand fill in the template.
Give the pull request a Conventional Commits title, such as
feat(camera): add LookAsync or fix: map clan timestamps as milliseconds. A workflow labels the pull
request from the title, and the label decides where the change appears in the release notes:
| Title type | Label | Release-notes section |
|---|---|---|
feat, perf |
enhancement |
Features |
fix |
bug |
Fixes |
docs |
documentation |
Documentation |
chore, refactor, test, build, ci, style |
none | Internal |
Add ! after the type for a breaking change (feat!: …), and describe what consumers have to change
in the template's Breaking changes section. The release notes are written from it.
CI builds the solution, runs every test on both hosts and enforces the coverage gate. SonarQube
analyses develop after the merge.
- Bugs and feature requests: the issue tracker, using its templates. Remove tokens, Steam ids and server addresses from anything you paste.
- Questions and ideas: Discussions.
- Security vulnerabilities: privately, as described in SECURITY.md.