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 ¶
- func HistoryFilename() string
- func SetVerbose(v bool)
- type ChangeLine
- type Changelog
- func (c *Changelog) AddLineToSubsection(versionNum, subsectionName string, line *ChangeLine)
- func (c *Changelog) AddLineToVersion(versionNum string, line *ChangeLine)
- func (c *Changelog) GetSubsection(versionNum, subsectionName string) *Subsection
- func (c *Changelog) GetSubsectionOrCreate(versionNum, subsectionName string) *Subsection
- func (c *Changelog) GetVersion(versionNum string) *Version
- func (c *Changelog) GetVersionOrCreate(versionNum string) *Version
- func (c *Changelog) String() string
- type Subsection
- type Version
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 NewChangelogFromFile ¶
NewChangelog builds a changelog from the file at the provided filename.
func NewChangelogFromReader ¶
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 ¶
GetVersion fetches the Version struct which matches the versionNum. Returns nil if no version was found matching the given versionNum.
func (*Changelog) GetVersionOrCreate ¶
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.
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 ¶
NewVersion allocates a new Version struct with all the fields initialized except {{.Date}}.