README

changelog

Parse markdown-esque changelogs (like our example), parse out versions, sections, changes & references. Motivation: automate update of changelogs

Bundled with a command, changelogger.

Build Status

changelogger command

Installation
$ go get github.com/parkr/changelog/changelogger
Usage
$ $GOPATH/bin/changelogger
$ $GOPATH/bin/changelogger -h

changelog package

Installation
$ go get github.com/parkr/changelog
Usage
// Parse changelog at a given filename
changes, err := changelog.NewChangelogFromFile("CHANGELOG.md")

// Discover the filename of your changelog
filename := changelog.HistoryFilename()

// Parse changelog from some io.Reader
changes, err := changelog.NewChangeLogFromReader(req.Body)

License

MIT License, Copyright 2015 Parker Moore. See LICENSE for details.

Documentation

Overview

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func HistoryFilename

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

func SetVerbose(v bool)

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

Types

type ChangeLine

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

func (l *ChangeLine) String() string

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

type Changelog

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

func NewChangelog() *Changelog

NewChangelog creates a pristine Changelog.

func NewChangelogFromFile

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

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

func NewChangelogFromReader

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

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

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

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

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

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

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

func (c *Changelog) String() string

A Markdown string representation of the Changelog.

type Subsection

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

func NewSubsection(subsectionName string) *Subsection

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

func (*Subsection) String

func (s *Subsection) String() string

String returns the markdown representation of the subsection.

type Version

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

func NewVersion(versionNum string) *Version

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

func (*Version) String

func (v *Version) String() string

String returns the markdown representation for the version.

Directories

Path Synopsis