Development

For anyone changing the library or its data. AGENTS.md at the repository root holds the rules in full; this page is the tour.

Layout

Path	What it holds
RandomNameGeneratorLibrary/	The library: three generators, three interfaces, three extension classes, the base class, the two obsolete tools and the seven Resources.*.stripped lists (embedded, LF, UTF-8).
RandomNameGeneratorUnitTests/	xunit.v3 tests on net10.0 and net48: behaviour, resource integrity, the public API surface, the README's example rows.
tests/Golden/	The contract: every answer the published 2.2.0 gave, recorded per runtime by tests/Golden/Capture, plus PublicApi-2.2.0.txt. Never edited.
tests/RandomNameGeneratorLibrary.GoldenTests/	Replays the recordings against the current build. Exceptions/ pins the 35 place-derived cases per runtime that 2.3.0 changed on purpose.
tests/consumers/	Builds and runs a fresh consumer of the packed package (in CI) or the published one (after a release) on net10.0 and net48.
tools/CensusTools/	Rebuilds the person and place lists from the Census files; SOURCES.md has the URLs and hashes.
tools/StarLists/build_star_lists.py	Rebuilds the three star lists from the IAU, Bright Star and Hipparcos sources.
ai-docs/	Notes, decisions and plans from past work sessions, for people and agents alike. Start at HANDOFF.md.

Build and test

The SDK is pinned in global.json (10.0.401 at the time of writing). On Windows the net48 tests run as well.

dotnet restore --locked-mode
dotnet format --verify-no-changes
dotnet build -c Release
dotnet test -c Release
dotnet pack RandomNameGeneratorLibrary -c Release -o artifacts
bash tests/consumers/run.sh 2.3.0 artifacts

Lock files are committed. After changing a package reference, run plain dotnet restore and commit the updated packages.lock.json. The library has no dependencies, and keeping it that way is a rule.

The golden contract

The same seed gives the same names, on .NET Framework and on .NET, from one version to the next. The golden tests hold 426 recorded calls per runtime and fail on any difference. A change that alters a recorded answer (a list, the order of Random calls, an exception type or message) is a deliberate decision. It gets an entry in ai-docs/decisions/ and a changelog line. It also gets either a new API name or a pinned exception file, like the one 2.3.0's place cases have. Recordings are never regenerated. PublicApi-2.2.0.txt guards type, member and parameter names; package validation at pack time guards the API shape against the previous release.

Changing a list

The lists are data: a changed line changes seeded output. To rebuild after a Census or IAU source changes:

dotnet run --project tools/CensusTools -c Release -- place places2k.txt RandomNameGeneratorLibrary/Resources.places2k.txt.stripped
dotnet run --project tools/CensusTools -c Release -- person dist.all.last RandomNameGeneratorLibrary/Resources.dist.all.last.stripped
python tools/StarLists/build_star_lists.py --cache <dir>

Then treat the result as a contract change, as above. On Windows, Python needs PYTHONIOENCODING=utf-8 to print Greek and accented names.

Continuous integration

ci.yml runs on every push and pull request. Its steps: locked restore, format check, build, and a restore that fails on any NuGet audit finding. Then tests on Linux (net10.0) and Windows (net10.0 and net48), pack with package validation, a check of the package's contents, and the consumers against the packed package. Actions are pinned to commit SHAs. Dependabot proposes NuGet, SDK and action updates weekly, after a seven-day cooldown.

Releasing

Nothing reaches nuget.org without the maintainer. release.yml publishes through Trusted Publishing (GitHub OIDC, no stored API key) from a job that waits for approval on the nuget environment.

1. Add the section to CHANGELOG.md, with its date, and set <Version> in RandomNameGeneratorLibrary.csproj.
2. Merge and wait for ci to be green on master.
3. Tag the commit v<version> and push the tag. Tag only after green: tags are not force-pushed here, so a tag on a failing commit burns the version number.
4. release.yml checks that the tag matches the version and sits on master, tests on Linux and Windows, packs, attests the package and waits for the approval. After it, the job pushes to nuget.org and creates the GitHub Release with the changelog section and the packages.
5. Run verify-published.yml with the version. It checks the release from nuget.org on Linux, Windows and macOS.
6. Set PackageValidationBaselineVersion to the released version.

A prerelease such as v2.3.0-beta.1 follows the same path; that is how the release path for 2.3.0 was rehearsed.

Rules in one place

AGENTS.md: the contract, the targets (no net5+ APIs without an #if), tests for every artifact, no dependencies, SHA-pinned actions, LF line endings, documentation in ai-docs/, no AI attribution anywhere.