API Reference Language: C# Component: ReleaseContracts Audience: developer

ReleaseContracts

Type

UnreleasedEntryComposer

Source

Loads append-only release-note entries and inserts them into a stable living-note template.

Remarks

Entries are individual Markdown files in a flat, filename-sorted directory. This avoids concurrent edits to the shared living-note template when independent work streams describe their release-facing changes. Each entry begins with an exact section directive and may add nested headings or ordinary Markdown, but cannot introduce a new top-level section. The supported section identifiers are declared by the template's composition markers, so consumer projects can use their own release-note structure without a code change. Callers use the composed content for rendering or release preparation; the checked-in template remains stable until its owning release workflow resets it.

Method

LoadAsync

Task<UnreleasedEntrySet> LoadAsync(string entriesDirectory, CancellationToken cancellationToken)

Source

Loads and validates every entry file in a flat entries directory.

Parameters

entriesDirectory
Absolute entries-directory path.
cancellationToken
Token observed between file reads.

Returns

Validated entries and their absolute source paths, ordered by filename.

Exceptions

UnreleasedEntryException
Thrown when an entry path or its Markdown directive is invalid.

Method

Compose

string Compose(string template, IEnumerable<UnreleasedEntry> entries, string destinationPath)

Source

Inserts validated entries at the end of their designated top-level template sections.

Parameters

template
Living-note template that contains one marker for each template-declared section.
entries
Validated entries to insert.
destinationPath
Absolute path of the composed living or versioned release note.

Returns

The deterministic composed release note.

Exceptions

UnreleasedEntryException
Thrown when the template does not have the expected marker shape.

Method

RebaseRelativeLinkDestinations

string RebaseRelativeLinkDestinations(string markdown, string entryPath, string destinationPath)

Source

Rebases relative Markdown link destinations from an entry source into its composed release-note destination.

Parameters

markdown
Validated entry Markdown.
entryPath
Absolute entry source path.
destinationPath
Absolute composed document path.

Returns

Entry Markdown whose relative inline and reference link destinations resolve from the composed document.

Remarks

Entry files live one directory below both releases/unreleased.md and versioned release notes. The composer therefore preserves each destination's target while recalculating its relative path from the composed document. External, rooted, query-only, and fragment-only destinations remain unchanged. The transformation deliberately excludes inline, fenced, and indented code so examples retain their original bytes.

Method

FindCodeBlockRanges

IReadOnlyList<MarkdownRange> FindCodeBlockRanges(string markdown)

Source

Collects source-coordinate ranges for code blocks parsed from entry Markdown.

Parameters

markdown
Entry Markdown whose code blocks are excluded from rewriting.

Returns

Half-open source ranges for every fenced or indented code block, including nested containers.

Method

AddCodeBlockRanges

void AddCodeBlockRanges(ContainerBlock container, List<MarkdownRange> ranges)

Source

Recursively adds code-block spans from a Markdown block container.

Parameters

container
Container whose descendants may include code blocks.
ranges
Collection receiving half-open source ranges.

Method

FindInlineCodeRanges

IReadOnlyList<MarkdownRange> FindInlineCodeRanges(string markdown)

Source

Collects source-coordinate ranges delimited by inline-code backticks.

Parameters

markdown
Entry Markdown whose inline-code spans are excluded from rewriting.

Returns

Half-open source ranges for matched inline-code delimiters and their contents.

Method

RewriteLinkDestinations

string RewriteLinkDestinations(string markdown, string entryDirectory, string destinationDirectory, int sourceOffset, IReadOnlyList<MarkdownRange> inlineCodeRanges)

Source

Rewrites eligible link destinations from an immutable source line.

Parameters

markdown
One source line outside a Markdown code block.
entryDirectory
Directory that resolves entry-relative destinations.
destinationDirectory
Directory that must resolve the composed destinations.
sourceOffset
Absolute offset of the source line in the entry Markdown.
inlineCodeRanges
Inline-code ranges in the original entry Markdown.

Returns

The line with eligible destination spans rebased without moving source coordinates.

Method

IsInInlineCodeRange

bool IsInInlineCodeRange(int position, IReadOnlyList<MarkdownRange> inlineCodeRanges)

Source

Determines whether a source position belongs to an inline-code span.

Parameters

position
Zero-based source position.
inlineCodeRanges
Inline-code ranges in the source Markdown.

Returns

true when the position is preserved as inline code.

Method

IsInMarkdownRange

bool IsInMarkdownRange(int position, IReadOnlyList<MarkdownRange> ranges)

Source

Determines whether a source position lies within any half-open Markdown range.

Parameters

position
Zero-based source position.
ranges
Half-open ranges to inspect.

Returns

true when the position is contained by a range.

Method

IntersectsMarkdownRange

bool IntersectsMarkdownRange(int start, int end, IReadOnlyList<MarkdownRange> ranges)

Source

Determines whether a source line overlaps any half-open Markdown range.

Parameters

start
Inclusive line-start source position.
end
Exclusive line-end source position.
ranges
Half-open ranges to inspect.

Returns

true when the line and a range share source content.

Method

CountRun

int CountRun(string value, int start, char character)

Source

Counts consecutive occurrences of a character from a source position.

Parameters

value
Source text to inspect.
start
Zero-based position where the candidate run begins.
character
Character expected in the run.

Returns

Number of consecutive matching characters.

Method

IsEntryPath

bool IsEntryPath(string repositoryRelativePath)

Source

Gets whether a repository-relative path can be an append-only unreleased entry.

Parameters

repositoryRelativePath
Slash-separated repository-relative path.

Returns

true when the path is a direct valid entry file.

Method

MarkerFor

string MarkerFor(string section)

Source

Gets the exact marker used by the living-note template for a section.

Parameters

section
Valid section identifier.

Returns

Exact HTML comment marker.

Method

GetTemplateMarkers

IReadOnlyList<TemplateMarker> GetTemplateMarkers(string template)

Source

Reads the unique composition markers declared by the living-note template.

Parameters

template
Living-note template containing composition markers.

Returns

Composition markers in their template order.

Exceptions

UnreleasedEntryException
Thrown when the template has no markers or repeats a section.

Type

MarkdownRange

Source

Half-open source-coordinate range in an entry Markdown document.

Parameters

Start
Inclusive zero-based source position.
End
Exclusive zero-based source position.

Type

UnreleasedEntry

Source

One validated append-only Markdown entry and its destination section.

Parameters

Path
Absolute source-file path.
Section
Stable section identifier selected by the file directive.
Markdown
Validated Markdown inserted at the section bottom.

Type

UnreleasedEntrySet

Source

Validated entries together with the source files release preparation removes after archival.

Parameters

Entries
Entries to compose.
Snapshots
Absolute source-file paths and content digests in deterministic filename order.

Property

Paths

IReadOnlyList<string> Paths { get; } Source

Gets absolute source-file paths in deterministic filename order.

Type

UnreleasedEntrySnapshot

Source

Captures one append-only entry source file and the bytes release preparation must revalidate before deletion.

Parameters

Path
Absolute source-file path.
Sha256
Lowercase SHA-256 digest of the source bytes.

Type

UnreleasedEntryException

Source

Indicates an invalid append-only unreleased entry or living-note template marker shape.

Type

PackageReleaseLink

Source

Describes how a package documentation surface reaches the release narrative that applies to it.

Remarks

A coordinated link is deliberately an alias rather than a version lookup. At release preparation time it resolves to releases/current.md ; the checked-in pointer in each exported docs tree then names that tree's immutable tagged note. Use an explicit link only when a package intentionally has a different release narrative.

Type

PackageReleaseLinkResolver

Source

Resolves and validates package-index release-link fields shared by package and release tooling.

Method

TryResolve

bool TryResolve(string? releaseTrack, string? releaseNotesPath, out PackageReleaseLink? link, out string? error)

Source

Resolves a package release link from package-index YAML values.

Parameters

releaseTrack
Optional release_track YAML value.
releaseNotesPath
Optional release_notes_path YAML value.
link
The resolved link when validation succeeds.
error
A maintainer-facing validation error when validation fails.

Returns

true when the fields describe a supported link and link is non-null.

Remarks

Rows without release_track retain the historical explicit-path meaning when they declare a non-empty release_notes_path , so old release manifests and archived package-index snapshots remain readable. Every row still needs one source. New coordinated rows must not also carry a versioned path: that combination makes it unclear whether a reader should follow the frozen alias or the mutable package-index value.

Enum

PackageReleaseTrack

Source

Selects the package release-link policy.