relic

README

Relic

Relic is a library to help with versioning your projects by storing release metadata and versions as code.

Purpose

Relic allows you define your project version history in a declarative style by defining a History object somewhere in your project whose methods allow you to declare releases defined by a version number and release note. It ensures your releases have monotonically increasing unique versions.

Relic can generate the current version and a complete changelog using this information.

By keeping the changelog with the version they are synchronised and you are reminded to produce the changelog.

Usage

// Add file to your project in which to record your projects revision history
package project

import (
	"fmt"
	"text/template"
	"github.com/monax/relic"
)

// Create a global variable in which to store your project history.
// MustDeclareReleases allows you to declare your releases by specifying a version and release note
// for each release. To add a new release just insert it at the top.
var history relic.ImmutableHistory = relic.NewHistory("Relic").
	MustDeclareReleases(
		"1.1.0",
		`Add ImmutableHistory and tweak suggested usage docs`,
		"1.0.1",
		`Documentation fixes and typos`,
		"1.0.0",
		`Minor improvements:
- Rename RecordReleases to DeclareReleases (breaking API change)
- Add sample snippet to readme
- Sign version tags
`,
		"0.0.1",
		`First release of Relic extracted from various initial projects, it can:
- Generate changelogs
- Print the current version
- Ensure valid semantic version numbers
`,
)

func PrintReleaseInfo() {
	// Print the current version
	fmt.Printf("%s (Version: %v)\n", history.Project(), history.CurrentVersion().String())
	// Print the complete changelog 
	fmt.Println(history.Changelog())
	// Get specific release
	release, err := history.Release("0.0.1")
	if err != nil {
		panic(err)
	}
	// Print major version of release
	fmt.Printf("Release Major version: %v", release.Version.Major())
}

// You can also define histories with a custom template
var ProjectWithTemplate = relic.NewHistory("Test Project").
		WithChangelogTemplate(template.Must(template.New("tests").
			Parse("{{range .Releases}}{{$.Name}} (v{{.Version}}): {{.Notes}}\n{{end}}"))).
		MustDeclareReleases(
			"0.1.0",
			"Basic functionality",
			"0.0.2",
			"Build scripts",
			"0.0.1",
			"Proof of concept",
		)

See Relic's own project package and Makefile for suggested usage within a project.

Dependencies

Go standard library and tooling plus Make and Bash for builds (but not required).

Documentation

Index

• Variables
• func EnsureReleasesUniqueValidAndMonotonic(rs []Release) error
• type History
  • func NewHistory(projectName string) *History
  • func (h *History) Changelog() (string, error)
  • func (h *History) CurrentNotes() string
  • func (h *History) CurrentVersion() Version
  • func (h *History) DeclareReleases(releaseLikes ...interface{}) (*History, error)
  • func (h *History) MustChangelog() string
  • func (h *History) MustDeclareReleases(releaseLikes ...interface{}) *History
  • func (h *History) Project() string
  • func (h *History) Release(versionLike interface{}) (Release, error)
  • func (h *History) WithChangelogTemplate(tmpl *template.Template) *History
• type ImmutableHistory
• type Release
• type Version
  • func AsVersion(versionLike interface{}) (Version, error)
  • func ParseVersion(versionString string) (Version, error)
  • func (v Version) Major() uint8
  • func (v Version) Minor() uint8
  • func (v Version) Patch() uint8
  • func (v Version) String() string

Variables

var DefaultChangelogTemplate = template.Must(template.New("default_changelog_template").
	Parse(`# {{ .Project }} Changelog{{ range .Releases }}
## Version {{ .Version }}
{{ .Notes }}
{{ end }}`))

Functions

func EnsureReleasesUniqueValidAndMonotonic

func EnsureReleasesUniqueValidAndMonotonic(rs []Release) error

Checks that a sequence of releases are monotonically decreasing with each version being a simple major, minor, or patch bump of its successor in the slice

Types

type History

type History struct {
	ProjectName       string
	Releases          []Release
	ChangelogTemplate *template.Template
}

The purpose of History is to capture version changes and change logs in a single location and use that data to generate releases and print changes to the command line to automate releases and provide a single source of truth for improved certainty around versions and releases

func NewHistory

func NewHistory(projectName string) *History

Define a new project history to which releases can be added in code e.g. var history = relic.NewHistory().MustDeclareReleases(...)

func (*History) Changelog

func (h *History) Changelog() (string, error)

Get the changelog for the complete history

func (*History) CurrentNotes

func (h *History) CurrentNotes() string

Gets the release notes for the current version

func (*History) CurrentVersion

func (h *History) CurrentVersion() Version

func (*History) DeclareReleases

func (h *History) DeclareReleases(releaseLikes ...interface{}) (*History, error)

Adds releases to the History with the newest releases provided first (so latest is at top). Releases can be specified by pairs of version (string or struct), notes (string) or by sequence of Release (struct) or mixtures thereof.

func (*History) MustChangelog

func (h *History) MustChangelog() string

Generates changelog, panicking if there is an error

func (*History) MustDeclareReleases

func (h *History) MustDeclareReleases(releaseLikes ...interface{}) *History

Like DeclareReleases but will panic if the Releases list becomes invalid

func (*History) Project

func (h *History) Project() string

func (*History) Release

func (h *History) Release(versionLike interface{}) (Release, error)

Gets the Release for version given in versionString

func (*History) WithChangelogTemplate

func (h *History) WithChangelogTemplate(tmpl *template.Template) *History

Change the default changelog template from DefaultChangelogTemplate

type ImmutableHistory

type ImmutableHistory interface {
	// Get latest version
	CurrentVersion() Version
	// Get latest release note
	CurrentNotes() string
	// Get the project name
	Project() string
	// Get complete changelog
	Changelog() (string, error)
	// Get complete changelog or panic if error
	MustChangelog() string
	// Find the release specified by Version struct or version string
	Release(versionLike interface{}) (Release, error)
}

Provides the read-only methods of History to ensure releases are not accidentally mutated when it is not intended

type Release

type Release struct {
	Version Version
	Notes   string
}

type Version

type Version struct {
	// contains filtered or unexported fields
}

func AsVersion

func AsVersion(versionLike interface{}) (Version, error)

func ParseVersion

func ParseVersion(versionString string) (Version, error)

func (Version) Major

func (v Version) Major() uint8

func (Version) Minor

func (v Version) Minor() uint8

func (Version) Patch

func (v Version) Patch() uint8

func (Version) String

func (v Version) String() string