Documentation
¶
Overview ¶
Package changelog parses, classifies, and rewrites Keep a Changelog files.
All functions in this package are pure: they accept the changelog text and configuration as input and return new text and a classification result. They never read from the process environment, the file system, or git.
Index ¶
- Constants
- Variables
- func Classify(unreleased string, custom map[string]config.BumpType) (config.BumpType, error)
- func ExtractCurrentVersion(content string) string
- func ExtractUnreleased(content string) string
- func NextVersion(currentVersion string, bump config.BumpType) (string, error)
- func ReleaseName(moduleName, version string) string
- func ReleaseURL(ownerRepo, moduleName, version string) string
- func Rewrite(content string, opts RewriteOptions) string
- type RewriteOptions
- type UpdateRequest
- type UpdateResult
Constants ¶
const ( // SemverPattern is a regex pattern that matches a semantic version string // (per https://semver.org/spec/v2.0.0.html). Exposed for callers that need // to construct related expressions. SemverPattern = `(?P<major>0|[1-9]\d*)\.` + `(?P<minor>0|[1-9]\d*)\.` + `(?P<patch>0|[1-9]\d*)` + `(?:-` + `(?P<prerelease>` + `(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)` + `(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*` + `)` + `)?` + `(?:\+` + `(?P<buildmetadata>` + `[0-9a-zA-Z-]+` + `(?:\.[0-9a-zA-Z-]+)*` + `)` + `)?` )
Variables ¶
var ErrIncompleteBreaking = errors.New(
"### Changed or ### Removed section found with missing or incomplete description." +
" Per Keep a Changelog, these sections are for BREAKING CHANGES only and must include 'BREAKING CHANGE' in" +
" the description. If this is NOT a breaking change, please use a different section type: ### Added (new features)" +
", ### Fixed (bug fixes), ### Deprecated, or ### Security",
)
ErrIncompleteBreaking is returned when a `### Changed` or `### Removed` heading is present but no entry under it contains the literal phrase "BREAKING CHANGE".
var ErrNoChangesDetected = errors.New("no changes detected")
ErrNoChangesDetected is returned when an unreleased section is empty or absent and the module should be silently skipped.
var ErrUnrecognizedChangeType = errors.New("missing or unrecognized change type in unreleased section")
ErrUnrecognizedChangeType is returned when an unreleased section contains content that does not match any built-in or configured custom heading.
Functions ¶
func Classify ¶
Classify inspects an unreleased section and returns the appropriate bump type, taking custom change types into account.
The decision rules are:
- A `### Changed` or `### Removed` heading without the literal phrase "BREAKING CHANGE" anywhere in the section returns ErrIncompleteBreaking.
- With "BREAKING CHANGE" present, those sections drive a major bump.
- `### Added`, `### Deprecated`, `### Security` drive a minor bump.
- `### Fixed` drives a patch bump.
- Custom types are evaluated under the same priority order; a custom "major" mapping still requires the BREAKING CHANGE marker.
- The highest-priority match wins.
- An empty section returns ErrNoChangesDetected.
- Anything else returns ErrUnrecognizedChangeType.
func ExtractCurrentVersion ¶
ExtractCurrentVersion returns the most recent versioned heading in the changelog, or "0.0.0" when none is present (i.e. a first release).
func ExtractUnreleased ¶
ExtractUnreleased returns the body of the `## [Unreleased]` section, trimmed of surrounding whitespace. It returns an empty string when no unreleased section exists or the section is empty.
func NextVersion ¶
NextVersion increments currentVersion by bump, returning the resulting SemVer string (without a "v" prefix).
func ReleaseName ¶
ReleaseName returns the module-scoped release identifier ("vX.Y.Z" or "<module>/vX.Y.Z").
func ReleaseURL ¶
ReleaseURL returns the GitHub Release URL for a given module/version.
func Rewrite ¶
func Rewrite(content string, opts RewriteOptions) string
Rewrite returns a new changelog body that promotes the unreleased section to a versioned section. The original `## [Unreleased]` heading is preserved at the top with an empty body, and a new versioned heading is inserted directly below it.
Types ¶
type RewriteOptions ¶
type RewriteOptions struct {
ModuleName string
NextVersion string // bare semver, e.g. "1.2.3"
OwnerRepo string // "<owner>/<repo>"
// MatchSection is the unreleased body to match in the source content
// (i.e. the text that was originally extracted by ExtractUnreleased).
MatchSection string
// PromoteAs is the text to emit under the new versioned heading. It may
// differ from MatchSection when, e.g., a manual-release footer is added.
// When empty, MatchSection is used.
PromoteAs string
Now time.Time
}
RewriteOptions controls Rewrite. The new versioned heading links back to the GitHub Release URL derived from OwnerRepo, ModuleName, and NextVersion via ReleaseURL.
type UpdateRequest ¶
type UpdateRequest struct {
Content string
ModuleName string
OwnerRepo string
CustomTypes map[string]config.BumpType
ManualVersion string // empty means "calculate from content"
ManualReason string
Actor string
Now time.Time
}
UpdateRequest describes a single changelog update.
type UpdateResult ¶
type UpdateResult struct {
NextVersion string // bare semver, e.g. "1.2.3"
UnreleasedSection string // body promoted into the new versioned section (incl. manual footer)
NewContent string // full rewritten changelog body
Bump config.BumpType
Manual bool
}
UpdateResult is the outcome of a successful Update.
func Update ¶
func Update(req UpdateRequest) (UpdateResult, error)
Update performs the full pure transformation: extract -> classify -> bump -> (optional override) -> rewrite. It returns ErrNoChangesDetected when the unreleased section is empty.
Source Files