changelog: byparker.com/go/changelog Index | Files

package changelog

import "byparker.com/go/changelog"

changelog provides a means of parsing and printing markdown changelogs.

The basic structure of a changelog is a reverse-chronological list of versions and the changes they contain. Each version can have its own direct list of uncategorized changes, and can contain a set of subsections. Subsections are a means of categorizing sets of changes based on component or type of change. Each change consists of a summary and a reference – either a pull request or issue number, or a @mention to the contributing user.

A basic changelog might look something like:

## 1.0.0 / 2015-02-21

### Major Enhancemens

  * Added that big feature (#1425)

### Bug Fixes

  * Fixed that narsty bug with tokenization (@carla)

## 0.0.1 / 2015-02-20

  * Initial implementation
  * Tokenize a changelog (#1)

Index

Package Files

changelog.go convenience.go doc.go filefinder.go parse.go

func HistoryFilename Uses

func HistoryFilename() string

HistoryFilename discovers the correct filename for your history file based on files in the current working directory. It iterates through the files in your current directory looking for a file with some case-insensitive form of History.markdown or Changelog.markdown with any series of supported markdown file extensions.

func SetVerbose Uses

func SetVerbose(v bool)

SetVerbose sets the verbose flag to the value passed. If true is passed, verbose logging will be enabled.

type ChangeLine Uses

type ChangeLine struct {
    // What the change entails.
    Summary string
    // Reference can be either a username (e.g. @parkr) or a PR number
    // (e.g. #1234).
    Reference string
}

ChangeLine contains the data for a single change. Acceptable formats:

* This is a change (#1234)
* This is another change. (@parkr)
* This is a change w/o a reference.

The references must be encased in parentheses, and only one reference is currently supported.

func (*ChangeLine) String Uses

func (l *ChangeLine) String() string

String returns the markdown representation of the ChangeLine. E.g. " * Added documentation. (#123)"

type Changelog Uses

type Changelog struct {
    Versions []*Version
}

Changelog represents a changelog in its entirety, containing all the versions that are tracked in the changelog. For supported formats, see the documentation for Version.

func NewChangelog Uses

func NewChangelog() *Changelog

NewChangelog creates a pristine Changelog.

func NewChangelogFromFile Uses

func NewChangelogFromFile(filename string) (*Changelog, error)

NewChangelog builds a changelog from the file at the provided filename.

func NewChangelogFromReader Uses

func NewChangelogFromReader(reader io.Reader) (*Changelog, error)

NewChangelogFromReader builds a changelog from the contents read in through the reader it's passed.

func (*Changelog) AddLineToSubsection Uses

func (c *Changelog) AddLineToSubsection(versionNum, subsectionName string, line *ChangeLine)

AddLineToSubsection adds a ChangeLine to the given version's subsection's history.

For example, this could be used to add a change to v1.4.2's "Major Enhancements" subsection.

func (*Changelog) AddLineToVersion Uses

func (c *Changelog) AddLineToVersion(versionNum string, line *ChangeLine)

AddLineToVersion adds a ChangeLine to the given version's direct history. This is only to be used when it is inappropriate to add it to a subsection, or the version's changes don't warrant subsections.

func (*Changelog) GetSubsection Uses

func (c *Changelog) GetSubsection(versionNum, subsectionName string) *Subsection

GetSubsection fetches the Subsection struct which matches the versionNum & subsectionName. Returns nil if no version was found matching the given versionNum & subsectionName.

func (*Changelog) GetSubsectionOrCreate Uses

func (c *Changelog) GetSubsectionOrCreate(versionNum, subsectionName string) *Subsection

GetSubsection fetches the Subsection struct which matches the versionNum & subsectionName. If no subsection was found matching the given versionNum & subsectionName, it creates it and saves it to the Changelog.

func (*Changelog) GetVersion Uses

func (c *Changelog) GetVersion(versionNum string) *Version

GetVersion fetches the Version struct which matches the versionNum. Returns nil if no version was found matching the given versionNum.

func (*Changelog) GetVersionOrCreate Uses

func (c *Changelog) GetVersionOrCreate(versionNum string) *Version

GetVersion fetches the Version struct which matches the versionNum. If no version was found matching the given versionNum, it creates and saves it to the Changelog.

func (*Changelog) String Uses

func (c *Changelog) String() string

A Markdown string representation of the Changelog.

type Subsection Uses

type Subsection struct {
    Name    string
    History []*ChangeLine
}

Subsection contains the data for a given subsection. Acceptable format:

### Subsection Name Here

Common subsections are "Major Enhancements," and "Bug Fixes."

func NewSubsection Uses

func NewSubsection(subsectionName string) *Subsection

NewSubsection creates a subsection for the given name and initializes its history.

func (*Subsection) String Uses

func (s *Subsection) String() string

String returns the markdown representation of the subsection.

type Version Uses

type Version struct {
    Version     string
    Date        string
    History     []*ChangeLine
    Subsections []*Subsection
}

Version contains the data for the changes for a given version. It can have both direct history and subsections. Acceptable formats:

## 2.4.1
## 2.4.1 / 2015-04-23

The version currently cannot be prefixed with a `v`, but a date is optional.

func NewVersion Uses

func NewVersion(versionNum string) *Version

NewVersion allocates a new Version struct with all the fields initialized except {{.Date}}.

func (*Version) String Uses

func (v *Version) String() string

String returns the markdown representation for the version.

Package changelog imports 9 packages (graph). Updated 2016-07-20. Refresh now. Tools for package owners. This is an inactive package (no imports and no commits in at least two years).