notes

Documentation

Overview

Package notes parses and range-queries the P31 release-notes corpus: an authored, version-keyed YAML file per shipped a2a version plus one standing current-known-issues document (releasenotes/*.yaml and releasenotes/current/known-issues.yaml), embedded by the releasenotes package. It structurally parses (ParseReleaseNotes, the same syntax-only-decode idiom internal/space's ParseManifest uses), loads the whole embedded corpus in ascending version order (Load), and answers the two range questions `a2a whatsnew` needs: "everything newer than the version I last saw, up to the version I'm running" (Since) and "the entry for exactly this version" (Exactly).

Schema/policy validity of the corpus is NOT this package's job (D-011, the same split internal/space draws for space.yaml) — that is internal/schema's ValidateReleaseNotes and ValidateKnownIssues, consumed here only by this package's own tests as corpus-integrity gates: every embedded document must validate, or the gate reds before it ever ships.

Index

• Constants
• Variables
• func NewDetailDecoder() (release.DetailDecoder, error)
• func RenderMarkdown(rn ReleaseNotes, opts MarkdownOptions) string
• type Action
• type Change
  • func LoadCurrentKnownIssues(fsys fs.FS) ([]Change, error)
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type MarkdownOptions
• type ReleaseNotes
  • func AttachCurrentKnownIssues(selected, all []ReleaseNotes, issues []Change) []ReleaseNotes
  • func Exactly(all []ReleaseNotes, version string) (ReleaseNotes, bool)
  • func Load(fsys fs.FS) ([]ReleaseNotes, error)
  • func ParseReleaseNotes(raw []byte) (ReleaseNotes, error)
  • func Since(all []ReleaseNotes, from, upto string) []ReleaseNotes

Constants

const KindKnownIssue = "known-issue"

KindKnownIssue is the one Change.Kind value a renderer must treat differently, so it is named here rather than spelled as a literal at each surface. The other kinds (feat/fix/break/schema/policy — the schema's enum is the full list) all describe something that CHANGED in that version and render identically; a known-issue describes something that is BROKEN OR INCOMPLETE right now, which is a different statement to a reader and especially to an agent: it means "do not rely on this surface, use the named alternative". It remains valid for historical release documents. Current limitations live once in releasenotes/current/known-issues.yaml and are attached after range selection until the fix ships and removes them there.

Variables

var (
	// ErrReleaseNotesInvalid is returned when a release-notes YAML file
	// fails structural parse.
	ErrReleaseNotesInvalid = errors.New("notes: release notes file is not valid yaml")

	// ErrKnownIssuesInvalid is returned when the standing known-issues YAML
	// file fails structural parse.
	ErrKnownIssuesInvalid = errors.New("notes: current known issues file is not valid yaml")

	// ErrCorpusLoad is returned when Load fails to read or parse the
	// embedded release-notes corpus (a build-time defect, never expected
	// at runtime against the shipped binary).
	ErrCorpusLoad = errors.New("notes: corpus failed to load")
)

Sentinel errors, one per failure class (P1 idiom: internal/artifact, mirrored by internal/space/errors.go and internal/schema/errors.go).

Functions

func NewDetailDecoder

func NewDetailDecoder() (release.DetailDecoder, error)

NewDetailDecoder returns the one production adapter from the authored release-notes parser and schema corpus into P49's verified future detail cache.

func RenderMarkdown

func RenderMarkdown(rn ReleaseNotes, opts MarkdownOptions) string

RenderMarkdown projects one authored release-notes document into the human GitHub Release body. The YAML corpus remains the SSOT; this renderer adds only stable navigation and install/verification framing.

Types

type Action

type Action struct {
	Scope  string   `yaml:"scope" json:"scope"`
	Why    string   `yaml:"why" json:"why"`
	Detect []string `yaml:"detect,omitempty" json:"detect,omitempty"`
	Run    []string `yaml:"run,omitempty" json:"run,omitempty"`
}

Action is one change's actionability directive: whether the agent running a2a needs to do anything about this change (scope), why (why), and — when there is something to do — how to detect whether it applies (detect) and what to run (run). scope: "space" directives are commands for the reading agent to run through the normal write funnel; a2a never runs them itself.

type Change

type Change struct {
	ID      string   `yaml:"id" json:"id"`
	Kind    string   `yaml:"kind" json:"kind"`
	Impact  string   `yaml:"impact" json:"impact"`
	Subject string   `yaml:"subject" json:"subject"`
	Detail  string   `yaml:"detail" json:"detail"`
	Affects []string `yaml:"affects,omitempty" json:"affects,omitempty"`
	Action  Action   `yaml:"action" json:"action"`
}

Change is one entry in a release-notes file's changes list.

func LoadCurrentKnownIssues

func LoadCurrentKnownIssues(fsys fs.FS) ([]Change, error)

LoadCurrentKnownIssues reads the standing known-issues document. Release history stays version-keyed; this list is current state and is therefore queried independently of any --since range.

type Error

type Error struct {
	// Op names the failing operation (e.g. "ParseReleaseNotes", "Load").
	Op string
	// Input is the offending input, kept for diagnostics (may be empty).
	Input string
	// Err is the wrapped sentinel (see the vars above).
	Err error
}

Error is the small typed error every exported operation in this package returns on failure. It always wraps one of the sentinels above so callers can use errors.Is/As; it never panics on bad input.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type MarkdownOptions

type MarkdownOptions struct {
	RepositoryURL string
	ProjectURL    string
	Verification  string
}

MarkdownOptions carries release-page facts that do not belong to the release-notes data model itself.

type ReleaseNotes

type ReleaseNotes struct {
	Schema   string   `yaml:"schema" json:"schema"`
	Version  string   `yaml:"version" json:"version"`
	Released string   `yaml:"released" json:"released"`
	Headline string   `yaml:"headline" json:"headline"`
	Changes  []Change `yaml:"changes" json:"changes"`

	// Raw holds the exact bytes ParseReleaseNotes was given, so a caller
	// can hand them, unmodified, to a schema-validation seam that needs
	// the full document rather than just this struct's typed subset (the
	// same rationale space.Manifest.Raw documents). json:"-" keeps it out
	// of the agent-facing `whatsnew --json` / MCP StructuredContent shape —
	// that surface is the machine contract, not a debug dump.
	Raw []byte `yaml:"-" json:"-"`
}

ReleaseNotes is the parsed structural shape of one releasenotes/<version> .yaml file (P31 schema, schemas/release-notes/v1/release-notes.schema. json) — a structural YAML decode only, mirroring internal/space's ParseManifest/Manifest split (D-011): schema/policy validity is a separate concern (internal/schema's ValidateReleaseNotes), never re-implemented here.

func AttachCurrentKnownIssues

func AttachCurrentKnownIssues(selected, all []ReleaseNotes, issues []Change) []ReleaseNotes

AttachCurrentKnownIssues adds standing limitations to the newest selected release without changing the established []ReleaseNotes machine contract. If the strict version range is empty, the newest embedded release is used as a metadata carrier containing only the standing issues.

func Exactly

func Exactly(all []ReleaseNotes, version string) (ReleaseNotes, bool)

Exactly returns the single entry of all whose Version equals version, and whether one was found.

func Load

func Load(fsys fs.FS) ([]ReleaseNotes, error)

Load reads every *.yaml file at the root of fsys (typically releasenotes.FS, the embedded P31 corpus), parses each with ParseReleaseNotes, and returns them sorted by version ASCENDING (internal/version.OlderThan — the same comparator internal/space and internal/release use, spec 19 §7 anti-dup). A parse failure for any file is a returned error; there is no partial/best-effort result.

func ParseReleaseNotes

func ParseReleaseNotes(raw []byte) (ReleaseNotes, error)

ParseReleaseNotes structurally parses raw release-notes YAML bytes. Malformed YAML is a typed error wrapping ErrReleaseNotesInvalid; this is a syntax check only — schema validity is internal/schema's job (mirrors space.ParseManifest exactly).

func Since

func Since(all []ReleaseNotes, from, upto string) []ReleaseNotes

Since returns the entries of all (assumed already version-ascending, the shape Load returns) whose version is strictly GREATER than from and LESS-THAN-OR-EQUAL-TO upto, preserving ascending order. from == "" means "everything up to upto"; upto == "" means "everything strictly after from". A malformed from/upto/entry version (internal/version. OlderThan's ErrInvalidVersion) fails CLOSED for that comparison — the entry is excluded rather than guessed into the result.