Document usage end to end; least-privilege setup guide; CONTRIBUTING and SECURITY

.changeset/docs-usage-and-guides.md

@@ -0,0 +1,5 @@
+---
+"@neolution-ch/csag-azure-sql-federated-identity": patch
+---
+
+Rewrite the package README as a self-contained quickstart: every configuration key including `RefreshAheadWindow` and `EnableBackgroundRefresh`, all three `AddAzureSqlFederatedIdentity` overloads, obtaining the token from `IAzureSqlTokenProvider` and assigning it to `SqlConnection.AccessToken` with plain ADO.NET and with EF Core, the prerequisites on the Google and Microsoft side, and a troubleshooting table. Links are absolute so they work on nuget.org.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What does this PR change, and why? Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] Changeset added (`npx changeset`, or `npx changeset --empty` if the package is unaffected)
+- [ ] `dotnet build -c Release` is clean (no warnings)
+- [ ] `dotnet test -c Release` passes on `net8.0` and `net10.0`
+- [ ] Documentation updated where behaviour or configuration changed (package README, `docs/cloud-identity-setup.md`, Demo README)
+- [ ] `packages.lock.json` files updated and committed if package references changed

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing
+
+Thank you for helping improve Csag.AzureSqlFederatedIdentity. Bug reports, questions and pull requests are welcome on [GitHub](https://github.com/neolution-ch/Neolution.AzureSqlFederatedIdentity). For vulnerabilities, please follow [SECURITY.md](./SECURITY.md) instead of opening an issue.
+
+## Prerequisites
+
+- The .NET SDK pinned in [global.json](./global.json) (10.0.4xx; a newer 10.0 minor rolls forward), plus the **.NET 8 runtime**, because the tests also run on `net8.0`. `dotnet --list-runtimes` should list `Microsoft.NETCore.App 8.0.x` alongside 10.0.x.
+- [Node.js](https://nodejs.org/) 24 for the changesets tooling: run `npm ci` once in the repository root.
+- Docker, only if you want to build the Demo container (see the [Demo README](./Csag.AzureSqlFederatedIdentity.Demo/README.md)).
+
+## Build and test
+
+```shell
+dotnet restore --locked-mode        # what CI runs; fails if a packages.lock.json is out of date
+dotnet build -c Release             # warnings are errors in Release, so this is the gate to pass
+dotnet test -c Release              # runs the suite on net8.0 and net10.0
+dotnet test -c Release -f net10.0   # a single target framework, for a quicker loop
+dotnet pack Csag.AzureSqlFederatedIdentity -c Release -o ./nupkgs
+```
+
+The library targets `net8.0` and `net10.0`, and CI runs the tests on both; a change is not done until both are green. Build in `Release` before you push: `TreatWarningsAsErrors` is on and the StyleCop rules from `Neolution.CodeAnalysis` are enforced there, so a build that is clean in `Debug` can still fail. Fix every warning rather than suppressing it.
+
+## Code conventions
+
+The analyzers enforce most of these; the rest come from the existing code.
+
+- XML documentation on every member, public or private.
+- `this.` prefix for instance members.
+- `using` directives inside the namespace, sorted alphabetically with `System` namespaces first.
+- Nullable reference types are enabled; `ConfigureAwait(false)` on every `await` in the library.
+- Comments explain the non-obvious *why* of the code as it stands; they do not narrate edits or previous states.
+- Tests use xunit, Shouldly and NSubstitute, follow the `Given_<state>_When_<action>_Then_<outcome>` naming with Arrange/Act/Assert sections, and live in `Csag.AzureSqlFederatedIdentity.UnitTests`. Read an existing test class before adding one.
+
+## Dependencies
+
+Package versions are managed centrally with transitive pinning:
+
+1. Add or change the version in [Directory.Packages.props](./Directory.Packages.props).
+2. Reference the package in the project file without a version: `<PackageReference Include="Package.Name" />`.
+3. Run `dotnet restore` (without `--locked-mode`) so that the `packages.lock.json` files update, and commit them together with the change.
+
+Dependabot proposes routine updates and generates their changesets automatically.
+
+## Changesets
+
+Releases follow the [neolution-ch release playbook](https://github.com/neolution-ch/release-playbook) with [Changesets](https://github.com/changesets/changesets); the [root README](./README.md#release-process) describes the pipeline. What it means for a pull request:
+
+- Every PR that changes the library needs a changeset file in `.changeset/`. Run `npx changeset`, pick the bump type and describe the change **for consumers of the package**; the text becomes the CHANGELOG entry.
+- The package is on a `0.x` version, so the bump convention is: **minor** for a breaking or behaviour-changing change, **patch** for a fix or for documentation that ships inside the package (the package README does).
+- A change that does not touch the package, such as CI, repository documentation or the Demo, still needs a changeset so that the check passes: run `npx changeset --empty`, which creates a file with an empty front matter.
+- CI's **Changeset Check** fails a PR without a changeset. Do not edit `CHANGELOG.md` or the version in the `.csproj` by hand; the "chore: version packages" PR does that.
+
+A changeset file looks like this:
+
+```markdown
+---
+"@neolution-ch/csag-azure-sql-federated-identity": patch
+---
+
+Describe the change from the consumer's point of view.
+```
+
+## Pull requests
+
+- Branch from `main` and keep the PR focused on one topic; small, reviewable diffs are merged faster.
+- Complete the checklist in the PR template: a changeset, `dotnet build -c Release` clean, `dotnet test -c Release` green on both target frameworks, and documentation updated where behaviour or configuration changed (the package README, `docs/cloud-identity-setup.md` and the Demo README).
+- Never commit secrets or real identifiers. The Demo's `appsettings.json` ships with empty values on purpose; use user secrets or environment variables locally.
+- Explain *why* in the PR description; the diff shows *what*.
+- A maintainer reviews every PR, and CI must be green before it is merged.

Csag.AzureSqlFederatedIdentity.Demo/README.md

@@ -94,4 +94,4 @@ On Windows the credential file is `%APPDATA%\gcloud\application_default_credenti
 
 ## Deploy to Cloud Run
 
-Push the image to Artifact Registry and deploy it with the runtime service account set to the configured Google service account and the four settings supplied as environment variables. Cloud Run sends traffic to port 8080, which is the port the image listens on. Section 4 of the [setup guide](../docs/cloud-identity-setup.md) has the details.
+Push the image to Artifact Registry and deploy it with the runtime service account set to the configured Google service account and the four settings supplied as environment variables. Cloud Run sends traffic to port 8080, which is the port the image listens on. The [setup guide](../docs/cloud-identity-setup.md) covers the Cloud Run configuration in detail.