changelog

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 9, 2023 License: MIT Imports: 12 Imported by: 1

README

go-changelog

Go Reference Code Coverage Go Report Card Release License

Golang package for changelog file creation/parsing

Features

Manual

  • Install with go get -u github.com/anton-yurchenko/go-changelog
Examples
Create a changelog file
package main

import (
    changelog "github.com/anton-yurchenko/go-changelog"
    "github.com/spf13/afero"
)

func main() {
    c := changelog.NewChangelog()
    c.SetTitle("Changelog")
    c.SetDescription("This file contains changes of all releases")

    c.AddUnreleasedChange("fixed", []string{"Bug"})
    c.AddUnreleasedChange("added", []string{"Feature"})

    r, err := c.CreateReleaseFromUnreleasedWithURL("1.0.0", "2021-05-31","https://github.com/anton-yurchenko/go-changelog/releases/tag/v1.0.0")
    if err != nil {
        panic(err)
    }

    if err := r.AddChange("changed", "User API"); err != nil {
        panic(err)
    }
    r.AddNotice("**This release contains breaking changes**")

    if err := c.SaveToFile(afero.NewOsFs(), "./CHANGELOG.md"); err != nil {
        panic(err)
    }
}
Parse an existing changelog file
package main

import (
    "fmt"
    changelog "github.com/anton-yurchenko/go-changelog"
)

func main() {
    p, err := changelog.NewParser("./CHANGELOG.md")
    if err != nil {
        panic(err)
    }

    c, err := p.Parse()
    if err != nil {
        panic(err)
    }

    fmt.Printf("Changelog contains %v releases", c.Releases.Len())
}
Update an existing changelog file
Click to expand 
package main

import (
    changelog "github.com/anton-yurchenko/go-changelog"
    "github.com/spf13/afero"
)

func main() {
    p, err := changelog.NewParser("./CHANGELOG.md")
    if err != nil {
        panic(err)
    }

    c, err := p.Parse()
    if err != nil {
        panic(err)
    }

    r := c.GetRelease("1.2.1")
    if r == nil {
        panic("Release does not exists")
    }

    r.Yanked = true

    c.SaveToFile(afero.NewOsFs(), "./CHANGELOG.md")
    if err != nil {
        panic(err)
    }
}

Notes

  • Releases are sorted by their Semantic Version
  • Scopes are sorted by their importance
  • SaveToFile will overwrite the existing file, and anything that does not match the changelog format will be omitted

License

MIT © 2021-present Anton Yurchenko

Documentation

Index

Constants

View Source 
const (
	// General
	EmptyLineRegex string = `^\s*$`
	URLRegex       string = `` /* 242-byte string literal not displayed */
	SemVerRegex    string = `` /* 177-byte string literal not displayed */
	DateRegex      string = `([1-2][0-9][0-9][0-9])-([1-9]|[0][1-9]|[1][0-2])-([1-9]|[0][1-9]|[1-2][0-9]?|[3][0-1]?)`
	DateFormat     string = `2006-01-02`
	// Margins
	TitleRegex                       string = `^#\s*(?P<title>\S*)\s*$`
	UnreleasedTitleRegex             string = `^## \[(?P<title>Unreleased)\]$`
	UnreleasedTitleWithLinkRegex     string = `^## \[(?P<title>Unreleased)\]\((?P<url>` + URLRegex + `)\)$`
	VersionTitleRegex                string = `^## \[(?P<version>` + SemVerRegex + `)\] - (?P<date>` + DateRegex + `)(?P<yanked> \[YANKED\])?$`
	VersionTitleWithLinkRegex        string = `^## \[(?P<version>` + SemVerRegex + `)\]\((?P<url>` + URLRegex + `)\) - (?P<date>` + DateRegex + `)(?P<yanked> \[YANKED\])?$`
	MarkdownUnreleasedTitleLinkRegex string = `^\[(?P<title>Unreleased)\]: (?P<url>` + URLRegex + `)$`
	MarkdownVersionTitleLinkRegex    string = `^\[(?P<version>` + SemVerRegex + `)\]: (?P<url>` + URLRegex + `)$`
	// Scopes
	AddedScopeRegex      string = `^### (?P<scope>Added)$`
	ChangedScopeRegex    string = `^### (?P<scope>Changed)$`
	DeprecatedScopeRegex string = `^### (?P<scope>Deprecated)$`
	RemovedScopeRegex    string = `^### (?P<scope>Removed)$`
	FixedScopeRegex      string = `^### (?P<scope>Fixed)$`
	SecurityScopeRegex   string = `^### (?P<scope>Security)$`
	EntryRegex           string = `^(?P<marker>[-*+]\s*)(?P<entry>.*)$`
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Changelog 

type Changelog struct {
	Title       *string
	Description *string
	Unreleased  *Release
	Releases    Releases
}

Changelog reflects content of a complete changelog file

func NewChangelog added in v1.0.0 

func NewChangelog() *Changelog

NewChangelog returns an empty changelog.

func (*Changelog) AddUnreleasedChange added in v1.0.0 

func (c *Changelog) AddUnreleasedChange(scope string, change string) error

AddUnreleasedChange adds a scoped change to Unreleased section.

Supported scopes: [added, changed, deprecated, removed, fixed, security].

func (*Changelog) CreateRelease added in v1.0.0 

func (c *Changelog) CreateRelease(version, date string) (*Release, error)

CreateRelease creates new empty release.

This is a helper function that wraps Releases.CreateRelease function.

func (*Changelog) CreateReleaseFromUnreleased added in v1.0.0 

func (c *Changelog) CreateReleaseFromUnreleased(version, date string) (*Release, error)

CreateReleaseFromUnreleased creates a new release with all the changes from Unreleased section. This will also cleanup the Unreleased section.

func (*Changelog) CreateReleaseFromUnreleasedWithURL added in v1.0.0 

func (c *Changelog) CreateReleaseFromUnreleasedWithURL(version, date, url string) (*Release, error)

CreateReleaseFromUnreleased creates a new release with all the changes from Unreleased section. This will also cleanup the Unreleased section. Identical to CreateReleaseFromUnreleased but with an extra step of adding a URL to the release.

func (*Changelog) CreateReleaseWithURL added in v1.0.0 

func (c *Changelog) CreateReleaseWithURL(version, date, url string) (*Release, error)

CreateReleaseWithURL creates new empty release.

This is a helper function that wraps Releases.CreateReleaseWithURL function.

Identical to CreateRelease but with an extra step of adding a URL to the release.

func (*Changelog) GetRelease added in v1.0.0 

func (c *Changelog) GetRelease(version string) *Release

GetRelease returns a release for a provided version.

This is a helper function that wraps Releases.GetRelease function.

func (*Changelog) SaveToFile added in v1.0.0 

func (c *Changelog) SaveToFile(filesystem Filesystem, filepath string) error

SaveToFile formats the changelog struct according to a predefined format and prints it to file.

Possible options for Filesystem are: [afero.NewOsFs(), afero.NewMemMapFs()].

func (*Changelog) SetDescription added in v1.0.0 

func (c *Changelog) SetDescription(description string)

SetDescription updates a description of the changelog.

func (*Changelog) SetTitle added in v1.0.0 

func (c *Changelog) SetTitle(title string)

SetTitle updates a title of the changelog.

func (*Changelog) SetUnreleasedURL added in v1.0.0 

func (c *Changelog) SetUnreleasedURL(link string) error

SetUnreleasedURL configures a markdown URL for an Unreleased section.

func (*Changelog) ToString added in v1.0.0 

func (c *Changelog) ToString() string

ToString returns a Markdown formatted Changelog struct.

type Changes 

type Changes struct {
	Added      *[]string
	Changed    *[]string
	Deprecated *[]string
	Fixed      *[]string
	Notice     *string
	Removed    *[]string
	Security   *[]string
}

Changes are scoped changelog entries for a single version.

func (*Changes) AddChange added in v1.0.0 

func (c *Changes) AddChange(scope string, change string) error

AddChange adds a scoped change.

Supported scopes: [added, changed, deprecated, removed, fixed, security].

func (*Changes) AddNotice added in v1.0.0 

func (c *Changes) AddNotice(notice string)

AddNotice adds a notice to the changes.

func (*Changes) ToString added in v1.0.0 

func (c *Changes) ToString() string

ToString returns a Markdown formatted Changes struct.

type Filesystem added in v0.0.2 

type Filesystem interface {
	Stat(string) (fs.FileInfo, error)
	Open(string) (afero.File, error)
	Create(string) (afero.File, error)
}

Filesystem is an interface of a filesystem.

Possible options: [afero.NewOsFs(), afero.NewMemMapFs()].

type Parser 

type Parser struct {
	Filepath   string
	Filesystem Filesystem
	Buffer     []string
	Margins    struct {
		Lines      []int
		Title      *int
		Unreleased *int
		Releases   []int
		Links      []int
		Added      []int
		Changed    []int
		Deprecated []int
		Removed    []int
		Fixed      []int
		Security   []int
	}
}

Parser is basically a runtime that holds a raw changelog content, key file Margins, filesystem backend and other attributes.

func NewParser 

func NewParser(filepath string) (*Parser, error)

NewParser creates a new Changelog Parser.

func NewParserWithFilesystem 

func NewParserWithFilesystem(filesystem Filesystem, filepath string) (*Parser, error)

NewParser creates a new Changelog Parser using non default (OS) filesystem.

Possible options for Filesystem are: [afero.NewOsFs(), afero.NewMemMapFs()].

func (*Parser) Parse 

func (p *Parser) Parse() (*Changelog, error)

Parse a changelog file and return a Changelog struct.

type Release 

type Release struct {
	Version *string
	Date    *time.Time
	Yanked  bool
	URL     *string
	Changes *Changes
}

Release is a single changelog version

func (*Release) AddChange added in v1.0.0 

func (r *Release) AddChange(scope string, change string) error

AddChange adds a scoped change to the release.

This is a helper function that wraps Changes.AddChange function.

func (*Release) AddNotice added in v1.0.0 

func (r *Release) AddNotice(notice string)

AddNotice adds a notice to the release.

This is a helper function that wraps Changes.AddNotice function.

func (*Release) SetDate added in v1.0.0 

func (r *Release) SetDate(date string) error

SetDate configures a date of the release. Expected format: YYYY-MM-DD

func (*Release) SetURL added in v1.0.0 

func (r *Release) SetURL(link string) error

SetURL configures a URL of the release

func (*Release) SetVersion added in v1.0.0 

func (r *Release) SetVersion(version string) error

SetVersion configures a Semantic Version of a release.

func (*Release) ToString added in v1.0.0 

func (r *Release) ToString() (string, string)

ToString returns a Markdown formatted Release struct.

type Releases added in v1.0.0 

type Releases []*Release

Releases is a slice of releases

func (*Releases) CreateRelease added in v1.0.0 

func (r *Releases) CreateRelease(version, date string) (*Release, error)

CreateRelease creates new empty release.

func (*Releases) CreateReleaseWithURL added in v1.0.0 

func (r *Releases) CreateReleaseWithURL(version, date, url string) (*Release, error)

CreateReleaseWithURL creates new empty release.

Identical to CreateRelease but with an extra step of adding a URL to the release.

func (Releases) GetRelease added in v1.0.0 

func (r Releases) GetRelease(version string) *Release

GetRelease returns a release for a provided version.

func (Releases) Len added in v1.0.0 

func (r Releases) Len() int

Len return a total amount of Releases.

func (Releases) Less added in v1.0.0 

func (r Releases) Less(i, j int) bool

Less compares versions of two releases.

func (Releases) Swap added in v1.0.0 

func (r Releases) Swap(i, j int)

Swap replaces positions of two releases.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.