Release Facil

Release Facil

Overview

Use this skill to release Facil through the repo's normal tag-driven NuGet flow, then create a GitHub Release after the tag CI has successfully pushed the package to NuGet. Keep the release change small and user-facing: version fields, release notes, README and facil_reference.yaml updates when behavior or configuration changed, verification, commit, tag, push, CI/NuGet confirmation, and GitHub Release publication.

Workflow

1. Require a clean working directory before proceeding. If git status --short reports any changes, stop and ask the user whether to commit, stash, discard, or otherwise resolve them first.

2. Confirm the release shape before editing:

   • Bump Version in Directory.Build.props.
   • Keep PackageReleaseNotes in src/Facil.Package/Facil.Package.fsproj pointing at the versioned GitHub Release URL:

<PackageReleaseNotes>https://github.com/cmeeren/Facil/releases/tag/v/$(Version)</PackageReleaseNotes>

• Use v/<Version> for the release tag. The CI workflow publishes packages only for tags under refs/tags/v/.

3. Prepare the release content:

   • Update code and docs only as needed for the release.
   • Update RELEASE_NOTES.md with user-facing behavior, migration impact, and usage guidance.
   • For user-relevant changes, add a concise entry in the ### Unreleased section, creating that section if it does not exist.
   • When the release includes any breaking change, create or keep a #### Breaking subsection and place it before other categorizing subsections. Put every breaking release-note entry there; do not bury breaking changes under #### Changed, #### Fixed, or plain bullets.
   • Use categorizing subsections such as #### Added or #### Fixed only when the release notes are large enough that grouping materially improves readability; for small releases, prefer plain bullets under the version heading.
   • Within each release-note bullet list, whether under the version heading or a categorizing subsection, order entries by user impact and breadth first. Put broad runtime correctness and behavior changes before narrow edge cases, and put documentation/package-metadata-only entries last unless they are the main release purpose.
   • Describe the observable effect from the user's perspective. Avoid naming internal mechanisms or implying an opt-in/configuration choice unless users actually control it.
   • Keep implementation-only rationale out of README.md, RELEASE_NOTES.md, and facil_reference.yaml.
   • Update facil_reference.yaml when public YAML configuration behavior, options, defaults, examples, or reference text change.
   • Before tagging, rename the release notes heading from ### Unreleased to ### <Version> (<YYYY-MM-DD>), using the release date.
   • Inspect the versioned release notes before committing and tagging. The section should contain only intended public release notes, with no stale Unreleased heading and no private or implementation-only details.
   • Do not create or reuse the GitHub Release notes temp file yet; refresh it from the final tagged content after the successful NuGet push.

4. Verify locally. Mirror CI where practical, using the same release-critical environment variables and the Expecto console apps directly:

$env:FACIL_FORCE_REGENERATE = "1"
$env:FACIL_FAIL_ON_CHANGED_OUTPUT = "1"
$env:connectionString = "<connectionString>"

dotnet tool restore
dotnet fantomas --check .
dotnet build src/TestDb/TestDb.sqlproj -c Release
dotnet sqlpackage /Action:Publish /SourceFile:"src/TestDb/bin/Release/TestDb.dacpac" /TargetConnectionString:"$env:connectionString"
dotnet build src/Facil.Package -c Release
dotnet pack src/Facil.Package -c Release
dotnet build src/PackageTests -c Release
dotnet src/PackageTests/bin/Release/net10.0/PackageTests.dll --fail-on-focused-tests
dotnet build src/DbTests -c Release
dotnet src/DbTests/bin/Release/net10.0/DbTests.dll --fail-on-focused-tests

If a local SQL Server or connection string is unavailable, stop and report which CI-equivalent checks could not be run instead of replacing them with weaker dotnet test runs.

5. When packaging behavior or package metadata matters, inspect the produced nupkg/Facil.<Version>.nupkg metadata. Local pack can prove the package version and release-notes URL are embedded.

6. Commit and tag:

   • Use git-commit to execute the authorized commit; it routes message authoring to git-commit-message.
   • Use v/<Version> for releases, for example v/2.16.0.

7. Push the commit and tag. Successful tag CI publishes the package to NuGet.

8. Watch the tag CI run and confirm NuGet publication before creating a GitHub Release:

   • Find the CI run for the pushed v/<Version> tag, not just the branch push run.
   • This repo's tag runs can be found with gh run list --branch "v/<Version>":

$tag = "v/<Version>"
$repo = "cmeeren/Facil"
$run = @(gh run list --repo $repo --workflow ci.yml --branch $tag --event push --limit 1 --json databaseId,headBranch,status,conclusion,url | ConvertFrom-Json)
if (-not $run) { throw "No CI run found for tag $tag" }
$runId = $run[0].databaseId
gh run watch $runId --repo $repo --exit-status

• Confirm the tag run succeeded and that the Push step performed a real NuGet upload. The workflow uses --skip-duplicate, so a successful step can still mean the package already existed and was skipped. Inspect the fresh run logs; if the push was skipped as a duplicate, the push logs are unavailable, or NuGet publication is unclear, stop and inspect/report before creating a GitHub Release.
• Verify the exact package version is visible on NuGet with scripts/wait-for-nuget.js before creating a GitHub Release. Run from the repository root with Node.js 22 or newer. The helper checks every 30 seconds for up to ten minutes, bounds each request to 15 seconds, and exits nonzero on timeout or an unexpected HTTP response. It retries HTTP 404, 429, server errors, and network failures; it does not publish anything. Wait for completion using bounded tool waits rather than starting additional polling commands. Proceed only after exit code 0; otherwise report the failure and keep the GitHub Release unpublished.