relnote

Documentation

Overview

Package relnote supports working with release notes.

Its main feature is the ability to merge Markdown fragments into a single document. (See Merge.)

This package has minimal imports, so that it can be vendored into the main go repo.

Index

• func CheckAPIFile(apiFS fs.FS, filename string, docFS fs.FS, docRoot string) error
• func CheckFragment(data string) error
• func DumpMarkdown(d *md.Document)
• func GroupAPIFeaturesByFile(fs []APIFeature) (map[string][]APIFeature, error)
• func Merge(fsys fs.FS) (*md.Document, error)
• func NewParser() *md.Parser
• type APIFeature

Functions

func CheckAPIFile

func CheckAPIFile(apiFS fs.FS, filename string, docFS fs.FS, docRoot string) error

CheckAPIFile reads the api file at filename in apiFS, and checks the corresponding release-note files under docFS. It checks that the files exist and that they have some minimal content (see CheckFragment). The docRoot argument is the path from the repo or project root to the root of docFS. It is used only for error messages.

func CheckFragment

func CheckFragment(data string) error

CheckFragment reports problems in a release-note fragment.

func DumpMarkdown

func DumpMarkdown(d *md.Document)

DumpMarkdown writes the internal structure of a markdown document to standard output. It is intended for debugging.

func GroupAPIFeaturesByFile

func GroupAPIFeaturesByFile(fs []APIFeature) (map[string][]APIFeature, error)

GroupAPIFeaturesByFile returns a map of the given features keyed by the doc filename that they are associated with. A feature with package P and issue N should be documented in the file "P/N.md".

func Merge

func Merge(fsys fs.FS) (*md.Document, error)

Merge combines the markdown documents (files ending in ".md") in the tree rooted at fs into a single document. The blocks of the documents are concatenated in lexicographic order by filename. Heading with no content are removed. The link keys must be unique, and are combined into a single map.

Files in the "minor changes" directory (the unique directory matching the glob "*stdlib/*minor") are named after the package to which they refer, and will have the package heading inserted automatically and links to other standard library symbols expanded automatically. For example, if a file *stdlib/minor/bytes/f.md contains the text

[Reader] implements [io.Reader].

then that will become

[Reader](/pkg/bytes#Reader) implements [io.Reader](/pkg/io#Reader).

func NewParser

func NewParser() *md.Parser

NewParser returns a properly configured Markdown parser.

Types

type APIFeature

type APIFeature struct {
	Package string // package that the feature is in
	Build   string // build that the symbol is relevant for (e.g. GOOS, GOARCH)
	Feature string // everything about the feature other than the package
	Issue   int    // the issue that introduced the feature, or 0 if none
}

An APIFeature is a symbol mentioned in an API file, like the ones in the main go repo in the api directory.