Skip to content

Example: NCore packages

packages.md is a repository-level page that records the NuGet packages a repository produces, the libraries each package contains, and the pipeline that packs it. Doc gen produces it at the root of the repository's documentation, only when a package pipeline is found. For an SDK-style (NCore) library there is normally no .nuspec: the .csproj and the pipeline are the package manifest, so the page reports what they declare instead.

What reviewers should check

  • The package is found even though the repository has no .nuspec. The nuspec file row says None, and no .nuspec path is invented.
  • Pack method states the SDK method and the pipeline variable that names the project (projectFile), not a NuGet CLI or includeReferencedProjects method.
  • Target frameworks lists every moniker from <TargetFramework> or <TargetFrameworks>. A moniker past end of support or malformed (for example .net8.0) is also raised in the tech debt findings.
  • Package ID source and Version source name where each value comes from (csproj property, Directory.Build.props, or pipeline variable), and dependency versions say whether they are inline or centrally managed. A pipeline-supplied version is never reported as the SDK default 1.0.0.
  • Bundled assemblies lists every assembly copied into the package by the packing target, and the Libraries included table marks each one sdk-bundled. A bundled PrivateAssets="All" project is never listed as a separate NuGet dependency.
  • The packed project's own library is pipeline-packed, and every library row names a real project file.
  • Library names link to their overview.md only when that documentation set exists; otherwise they are plain text.
  • ## Sources lists the pipeline file, solution, and every project file named in the tables.

Example

The document below is a complete, correct packages.md for a fictional SDK-packed library repository.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

# SAIF.NCore.Messaging - Packages

This page documents the NuGet packages produced by this repository, the libraries included in each package, and the pipeline that produces them.

---

## Packages

### `SAIF.NCore.Messaging`

| Field | Value |
| --- | --- |
| Package ID | `SAIF.NCore.Messaging` |
| Pack method | dotnet pack - SDK project (projectFile) |
| Pipeline file | `.azdo/SAIF.NCore.Messaging/azure-pipelines.yml` |
| Solution scope | `SAIF.NCore.Messaging.sln` |
| Primary project | `src/SAIF.NCore.Messaging/SAIF.NCore.Messaging.csproj` |
| nuspec file | None |
| Target frameworks | `net8.0` |
| Package ID source | `PackageId` property in `SAIF.NCore.Messaging.csproj` |
| Version source | Pipeline-supplied (`/p:Version=` from the `PackageVersion` pipeline variable); dependency versions inline (`PackageReference Version`) |
| Bundled assemblies | `SAIF.NCore.Messaging.Serialization.dll` (via `CopyProjectReferencesToPackage`) |

#### Libraries included

| Library | Project file | Included via |
| --- | --- | --- |
| [`SAIF.NCore.Messaging`](docs/libraries/saif-ncore-messaging/overview.md) | `src/SAIF.NCore.Messaging/SAIF.NCore.Messaging.csproj` | `pipeline-packed` |
| [`SAIF.NCore.Messaging.Serialization`](docs/libraries/saif-ncore-messaging-serialization/overview.md) | `src/SAIF.NCore.Messaging.Serialization/SAIF.NCore.Messaging.Serialization.csproj` | `sdk-bundled` |

---

## Sources
- `.azdo/SAIF.NCore.Messaging/azure-pipelines.yml`
- `.azdo/SAIF.NCore.Messaging/variables/vars.yml`
- `SAIF.NCore.Messaging.sln`
- `src/SAIF.NCore.Messaging/SAIF.NCore.Messaging.csproj`
- `src/SAIF.NCore.Messaging.Serialization/SAIF.NCore.Messaging.Serialization.csproj`