relic

README

Relic

Relic is a small 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 add releases defined by a version and release notes. It ensures you releases form a valid monotonic progression of semantic version compliant tagged releases.

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

By keeping the changelog with the version they are syncrhonised 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 Project = relic.NewHistory("Relic").
	MustDeclareReleases(
		"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", Project.Name, Project.CurrentVersion().String())
	// Print the complete changelog 
	fmt.Println(Project.Changelog())
	// Get specific release
	release, err := Project.Release("0.0.1")
	if err != nil {
		panic(err)
	}
	// Print major version of release
	fmt.Printf("Release Major version: %v", release.Version.Major())
}

//
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(name string) *History
  • func (h *History) Changelog() (string, error)
  • func (h *History) ChangelogForReleases(changelogTemplate *template.Template) (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) Release(versionLike interface{}) (Release, error)
  • func (h *History) WithChangelogTemplate(tmpl *template.Template) *History
• 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(`# {{ .Name }} 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 {
	Name              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(name string) *History

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

func (*History) Changelog

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

Get the changelog for the complete history

func (*History) ChangelogForReleases

func (h *History) ChangelogForReleases(changelogTemplate *template.Template) (string, error)

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

func (*History) MustDeclareReleases

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

Like DeclareReleases but will panic if the Releases list becomes invalid

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 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