relic

package module
v2.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 15, 2018 License: Apache-2.0 Imports: 6 Imported by: 20

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.

Relic can be used by CI systems to output version numbers for tagging artefacts and automatically pushing releases, such as goreleaser.

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", "https://github.com/monax/relic").
	MustDeclareReleases(
		"2.0.0 - 2018-08-15",
		`### Changed
- Versions must start from 0.0.1 (0.0.0 is reserved for unreleased)
- Default changelog format follows https://keepachangelog.com/en/1.0.0/
- NewHistory takes second parameter for project URL
- Dropped getters from Version since already passed by value so immutable

### Added
- Optional top (most recent) release may be provided with empty Version with (via empty string in DeclareReleases) whereby its notes will be listed under 'Unreleased'
- Optional date can be appended to version using the exact format <major.minor.patch - YYYY-MM-DD> e.g. '5.4.2 - 2018-08-14'
- Default changelog format footnote references standard github compare links to see commits between version tags
`,
		"1.1.0",
		`Add ImmutableHistory and tweak suggested usage docs`,
		"1.0.1",
		`Documentation fixes and typos`,
		"1.0.0",
		`Minor improvements:
- Rename DeclareReleases 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", "https://github.com/test/project").
		WithChangelogTemplate(template.Must(template.New("tests").
			Parse("{{range .Releases}}{{$.Name}} (v{{.Version}}): {{.Notes}}\n{{end}}"))).
		MustDeclareReleases(
			// Releases may optionally have a date which is included in the changelog
			"0.1.0 - 2016-07-12",
			"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

Constants

View Source 
const (
	VersionDateSeparator = " - "
	// Base of minor, major, and patch version numbers
	NumberBase = 10
	// Number of bits to represent version numbers
	UintBits = 8
)

Variables

View Source 
var DefaultChangelogTemplate = template.Must(template.New("default_changelog_template").
	Parse(`# [{{ .Project }}]({{ .ProjectURL }}) Changelog{{ range .Releases }}
## [{{ .Version }}]{{ if .Version.Dated }} - {{ .Version.FormatDate }}{{ end }}
{{ .Notes }}
{{ end }}
{{ range .ReleasePairs }}[{{ .Version }}]: {{ $.URL }}/compare/{{ .Previous.Version.Ref }}...{{ .Version.Ref }}
{{ end }}[{{ .FirstRelease.Version }}]: {{ $.URL }}/commits/{{ .FirstRelease.Version.Ref }}`))
View Source 
var DefaultDateLayout = "2006-01-02"
View Source 
var ZeroVersion = Version{}

Functions

func AsDate 

func AsDate(dateLike interface{}) (time.Time, error)

func AsString 

func AsString(stringLike interface{}) (string, error)

func EnsureReleasesUniqueValidAndMonotonic 

func EnsureReleasesUniqueValidAndMonotonic(rs []Release) error

func ValidateReleases 

func ValidateReleases(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
	ProjectURL        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, projectURL 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) CurrentRelease 

func (h *History) CurrentRelease() Release

func (*History) CurrentVersion 

func (h *History) CurrentVersion() Version

func (*History) DeclareReleases added in v1.0.0 

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

func (h *History) FirstRelease() Release

func (*History) MustChangelog 

func (h *History) MustChangelog() string

Generates changelog, panicking if there is an error

func (*History) MustDeclareReleases added in v1.0.0 

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

Like DeclareReleases but will panic if the Releases list becomes invalid

func (*History) Project added in v1.1.0 

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

func (h *History) ReleasePairs() []ReleasePair

func (*History) URL 

func (h *History) URL() string

func (*History) WithChangelogTemplate 

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

Change the default changelog template from DefaultChangelogTemplate

type ImmutableHistory added in v1.1.0 

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 ReleasePair 

type ReleasePair struct {
	Release
	Previous Release
}

type Version 

type Version struct {
	Major uint8
	Minor uint8
	Patch uint8
	Date  time.Time
}

func AsVersion 

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

func ParseDatedVersion 

func ParseDatedVersion(versionString string) (Version, error)

func ParseVersion 

func ParseVersion(versionString string) (Version, error)

func (Version) Dated 

func (v Version) Dated() bool

func (Version) FormatDate 

func (v Version) FormatDate() string

func (Version) Ref 

func (v Version) Ref() string

func (Version) Semver 

func (v Version) Semver() string

func (Version) String 

func (v Version) String() string

Source Files

View all Source files

Directories

Path Synopsis
cmd/changelog
cmd/notes
cmd/version

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.