Contributing to Signal.NET
Thanks for your interest! This guide covers the local setup and the conventions the build enforces.
Prerequisites
- The .NET SDK pinned in
global.json(.NET 11 preview; C# 15 preview features such as unions are used) - Docker, only for end-to-end testing against a real signal-cli-rest-api container
Build and test
dotnet restore
dotnet build
dotnet test
The unit and integration tests need no container, and neither does CI.
For an end-to-end check, start the container with docker compose up -d and link a device (see the
README). Put your number into user secrets rather than appsettings.json:
dotnet user-secrets --project samples/Signal.Sample.Bot set "Signal:Accounts:0" "+4915112345678"
dotnet run --project samples/Signal.Sample.Bot
Conventions
- Architecture: respect the layering in docs/architecture.md. Domain has no dependencies; Application defines ports; Infrastructure implements them; Hosting composes.
- Warnings are errors, including missing XML docs on public API (CS1591). Document every public member you add.
- Code style:
.editorconfigdescribes the style (file-scoped namespaces, braces,_camelCasefields). - Unions: use them for closed sets of alternatives (see docs/domain.md).
- Tests: add or adjust tests for every behaviour change.
- Docs: update
docs/andCHANGELOG.mdwhen behaviour, configuration or public API changes. - Never commit account data: phone numbers,
signal-cli-config/or secrets. The.gitignorecovers the usual locations.
Public API changes
Each library has PublicAPI.Shipped.txt (APIs in released versions) and PublicAPI.Unshipped.txt (APIs
added since). The build fails (RS0016/RS0017) when the public surface and these files disagree:
Adding API: run the analyzer's code fix (the lightbulb in the IDE), or fix everything at once:
dotnet format analyzers src/Signal.Domain/Signal.Domain.csproj --diagnostics RS0016 --severity infoRemoving or changing shipped API is a breaking change. Discuss it in an issue first.
The diff of these files is the API review of a pull request.
Documentation site
dotnet tool restore
dotnet docfx docfx.json --serve --port 8090 # 8080 is taken by signal-cli-rest-api
The site is published to GitHub Pages by .github/workflows/docs.yml on every push to main.
Templates
Test changes to templates/Signal.NET.Templates against locally packed libraries:
dotnet pack -c Release -o ./feed
dotnet new install ./feed/Nacorpio.Signal.Templates.<version>.nupkg
dotnet new signalbot -n TestBot -o ../TestBot # outside the repo, then add ./feed as a NuGet source
Releasing (maintainers)
Versions come from git tags (MinVer). Untagged builds are
0.2.0-preview.0.<height>.
- In
CHANGELOG.md, move the Unreleased entries under## [x.y.z] - YYYY-MM-DD. - Move the contents of every
PublicAPI.Unshipped.txtinto the matchingPublicAPI.Shipped.txt. - Commit, then tag and push, e.g.
git tag v0.2.0 && git push origin v0.2.0. Pre-releases usev0.2.0-preview.1. - Once the release is published, set
PackageValidationBaselineVersioninsrc/Directory.Build.propsto the new version, so the next release is checked for breaking changes against it.
.github/workflows/release.yml then:
- builds, tests and packs, and checks that the package versions match the tag;
- waits for your approval (environment
nuget), then publishes to nuget.org; - waits until every package is listed on nuget.org (
.github/scripts/wait-for-nuget.sh, up to 45 minutes); - creates the GitHub Release with the changelog section.
A rejected push or a package that never gets listed fails the run, so the GitHub Release is only created once the packages can actually be installed.
Publishing uses NuGet Trusted Publishing. The workflow exchanges a GitHub OIDC token for an API key that is valid for one hour, so no long-lived key is stored. One-time setup:
- nuget.org → your username → Trusted Publishing → add a policy: Repository Owner
Nacorpio, RepositorySignal.NET, Workflow Filerelease.yml, Environmentnuget. Under Select Scopes, allow Push new packages and Push new package versions with the glob patternNacorpio.Signal.*. The first release creates the package IDs, and the glob stops the policy from applying to your other packages. - GitHub → Settings → Environments → create
nuget. Add the environment secretNUGET_USER(your nuget.org profile name, not your email). Optionally add yourself as a required reviewer, so every release waits for approval before publishing.
Pull requests
- Fork the repository and create a branch from
main. - Make focused commits with descriptive messages.
- Open a pull request. CI builds and tests on Linux and Windows and packs the NuGet packages.