Lib.Release 10.4.0

Lib.Release

A .NET global tool that packs one or more projects in a target repository and publishes them to nuget.org. What to release is declared in a lib.release.json manifest that lives in the target repo. The tool only publishes a project when its declared version differs from the latest version already on nuget.org, so re-running it is safe and idempotent.

This README is written to help you (human or agent) author a lib.release.json for a repo you want to release — see The release manifest. The rest documents the CLI and the release pipeline.

• Package id: Lib.Release — Command: lib.release — Target framework: net10.0
• nuget.org: https://www.nuget.org/packages/lib.release
• Source: https://github.com/rzmoz/lib.release

Install

dotnet tool install --global Lib.Release

Requires the dotnet CLI on PATH (build/pack/push), and git on PATH when the target is a git repository (for the working-tree check). A non-git target skips the working-tree check and does not need git. The tool has no other runtime dependencies.

Usage

lib.release <Lib> [--ApiKey <key>] [--SkipTests] [-v|-d]

Options are case-insensitive. \* Required as either the flag or the NUGET_API_KEY env var — the run exits with InvalidArguments if neither is set.

Setup commands (no API key needed)

These modes are self-contained and non-interactive — an agent with only the installed tool (no source access) can discover and bootstrap everything from them:

Typical agent flow in a target repo: --check (is it compatible?) → --init (write the manifest) → review versions → release.

The release manifest: lib.release.json

lib.release.json is the only thing you author to make a repo releasable. It lists the projects to publish and the test projects to run. The tool reads the manifest in the target repo — not its own.

Where it goes

Put it anywhere in the repo; the tool searches recursively under <Lib> and uses the first match, so keep exactly one. The repository root is the conventional location.

Schema

A JSON Schema ships with the tool's source at lib.release.schema.json. Reference it from your manifest for editor validation and inline field docs — the tool ignores the $schema key:

{
  "$schema": "https://raw.githubusercontent.com/rzmoz/lib.release/main/lib.release.schema.json",
  "releases": [ { "project": "src/MyLib/MyLib.csproj", "version": "1.0.0", "prerelease": "" } ],
  "tests": [ "test/MyLib.Tests/MyLib.Tests.csproj" ]
}

Projects are referenced by their .csproj path relative to the repo root — there is no file-naming or folder-layout convention.

Migrating from the old format: earlier manifests identified projects by name (resolved by a <repo>/<name>/<name>.csproj convention). That format is no longer supported — the tool detects it and exits StaleManifest (14), and --check flags it. Run lib.release --migrate <dir> to convert it in place, preserving versions (it maps each name to its .csproj path), then commit. (To rebuild from scratch instead, use lib.release --init <dir> --force.)

Unknown keys are ignored by the tool, but the schema rejects them so authoring mistakes surface in your editor.

Generating a manifest

The fastest path is lib.release --init <dir>, which applies the rules below greedily and writes the file (preview first with lib.release --check <dir>). To produce or review one by hand, work through these steps — they are exactly what --init automates:

1. Find the packable projects. Look at every *.csproj in the repo (any folder, any depth) and keep only those that produce a NuGet package:
   • Include class libraries with packaging metadata, and tools with <PackAsTool>true</PackAsTool>.
   • Exclude test projects (*.Tests, or those with <IsPackable>false</IsPackable>), executable/sample apps (<OutputType>Exe</OutputType> console projects you don't ship), and anything else not meant for nuget.org.
2. Emit one releases entry per packable project. Set project to the csproj path relative to the repo root (e.g. src/Foo/Foo.csproj). No naming convention — the package id is taken from the csproj.
3. Set the version. Use the project's intended next Major.Minor.Patch. Set prerelease only for pre-release builds. (The committed .csproj version can stay a placeholder like 0.0.0; the tool injects the manifest version at release time — see pipeline.)
4. List test projects in tests[] by csproj path.
5. Add the $schema line so editors validate the file.
6. Save it at the repo root.

Then verify, before committing:

• every releases[].project path points to an existing .csproj;
• each release project carries packable metadata and ships its README (see packable csproj);
• every tests[] path points to an existing .csproj;
• every version is Major.Minor.Patch.

Examples

Multi-package library repo — DotNet.Basics

Releases three libraries and runs one test project. Note that the repo also contains a DotNet.Basics.Cli.Console sample app — it is deliberately not in releases because it isn't a published package.

{
  "$schema": "https://raw.githubusercontent.com/rzmoz/lib.release/main/lib.release.schema.json",
  "releases": [
    { "project": "DotNet.Basics/DotNet.Basics.csproj",                     "version": "12.12.3", "prerelease": "" },
    { "project": "DotNet.Basics.Pipelines/DotNet.Basics.Pipelines.csproj", "version": "12.11.1", "prerelease": "" },
    { "project": "DotNet.Basics.Cli/DotNet.Basics.Cli.csproj",             "version": "12.15.1", "prerelease": "" }
  ],
  "tests": [
    "DotNet.Basics.Tests/DotNet.Basics.Tests.csproj"
  ]
}

Single-package tool repo — this repo (Lib.Release)

One PackAsTool package, releasing itself, with one test project:

{
  "$schema": "./lib.release.schema.json",
  "releases": [
    { "project": "Lib.Release/Lib.Release.csproj", "version": "10.3.0", "prerelease": "" }
  ],
  "tests": [
    "Lib.Release.Tests/Lib.Release.Tests.csproj"
  ]
}

Project requirements

Referencing projects

A release entry's project is just the .csproj path relative to the repo root (forward slashes), e.g. src/Foo/Foo.csproj. Any layout works — flat, src/, nested, whatever. The package id is whatever the csproj produces: <PackageId> if set, else <AssemblyName>, else the file name. That package id is what the tool looks up on nuget.org (case-insensitively) to decide whether the version already exists.

Packable csproj metadata

Each release project should carry standard NuGet packaging metadata so it produces a valid package. The version fields can stay as placeholders (e.g. 0.0.0) — the tool overwrites them transiently at release time. Example from DotNet.Basics:

<PropertyGroup>
  <TargetFramework>netstandard2.1</TargetFramework>
  <Description>...</Description>
  <Authors>rzmoz</Authors>
  <RepositoryUrl>https://github.com/rzmoz/DotNet.Basics</RepositoryUrl>
  <Version>0.0.0</Version>
  <AssemblyVersion>0.0.0</AssemblyVersion>
  <FileVersion>0.0.0</FileVersion>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
  <PackageReadmeFile>README.md</PackageReadmeFile>
  <Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
  <None Remove="**/*.tmp" />
  <None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>

• <None Include="README.md" Pack="true" .../> together with <PackageReadmeFile>README.md</PackageReadmeFile> ships the per-project README into the package (required by nuget.org for a README to render).
• <None Remove="**/*.tmp" /> keeps the transient *.csproj.tmp backups the tool creates out of the package.

Test projects

Each entry in tests[] is a .csproj path (relative to the repo root). The tool runs each in release configuration and fails the release if any test fails.

Clean git working tree

If the target is a git repo, all changes must be committed before releasing — a dirty working tree aborts the run. A non-git target skips this check.

What it does (pipeline)

The tool runs these steps in order against the target repo. The first step to fail stops the run and the tool exits with the matching code from the exit-codes table — it reports the reason and never dumps a stack trace for a known failure.

Important: the csproj version edits from step 3 are transient. When the run finishes (success or failure), every patched .csproj is restored from its backup. The release version is sourced from lib.release.json, applied only for the duration of the pack/push, then reverted — your committed csproj files keep their original (placeholder) version.

Exit codes

Every code is in the 0–255 range. 0 is success; anything else is a distinct failure reason.

Release workflow

1. Bump version (and/or prerelease) in lib.release.json for the projects you want to publish.
2. Commit the change (if the repo is under git, the working tree must be clean).
3. Run lib.release <repo> --ApiKey <key>.

Only projects whose manifest version differs from what is already on nuget.org are packed and pushed; everything else is skipped. If no project needs releasing, the run exits early.