version

README

version

Go module to easily embed semantic versioning compliance with change history

Note that this module is not designed to parse and compare semantic versions. There is much better software designed for that task.

The goal is to provide a consistent interface for defining and reporting the version and changes of a Go package.

Usage

See the documentation for example.

Simply defining the global ChangeLog variable will conveniently record work history and doubles as package version definition. No function calls required. Similar to godoc, it's as simple to use as good comments.

Alternatively, you can just call Set() to set package version.

Features

• Compliant with Semantic Versioning (2.0.0)
• Can parse and generate changelog for release notes
• Can automatically integrate with flag package (e.g., -version, -changes, and other command-line flags)

Documentation

Overview

Example

package main

import (
	"fmt"

	"github.com/ardnew/version"
)

func init() {
	// list the version history directly in version.ChangeLog. the last element
	// is used as the current version of this package.
	version.ChangeLog = []version.Change{
		{
			Package: "mypkg",
			Version: "0.1.0",
			Date:    "Feb 26, 2020", // very many date-time formats recognized
			Description: []string{
				`initial commit`,
			},
		}, {
			Package: "mypkg",
			Version: "0.1.0+fqt",
			Title:   "Formal Test",
			Description: []string{
				`update user manual`,
			},
		}, {
			Package: "mypkg",
			Version: "0.2.0-beta+red",
			Title:   "Red Label",
			Date:    "20-March-9 17:45:23",
			Description: []string{
				`add feature: Dude`,
				`fix bug: Sweet`,
			},
		},
	}
}

func main() {

	// show that we are currently using the last entry in ChangeLog
	fmt.Printf("!! using ChangeLog version %q\n\n", version.String())

	// print a pretty changelog to stdout.
	version.PrintChangeLog()

	version.Set("0.1.4")
	fmt.Printf("!! set version to %q\n\n", version.String())

}

Output:

!! using ChangeLog version "0.2.0-beta+red"

――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
 mypkg version 0.1.0                              Wed, 26 Feb 2020 00:00:00 UTC
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
  initial commit

――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
 mypkg version 0.1.0+fqt - "Formal Test"
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
  update user manual

――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
 mypkg version 0.2.0-beta+red - "Red Label"       Mon, 09 Mar 2020 17:45:23 UTC
――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
  add feature: Dude
  fix bug: Sweet

!! set version to "0.1.4"

Index

• Variables
• func FprintChangeLog(w io.Writer)
• func FprintPackageVersion(w io.Writer)
• func IsSet() bool
• func Parse(version string) (major, minor, patch uint, pre, meta string)
• func ParseDate(date string) *time.Time
• func PrintChangeLog()
• func PrintPackageVersion()
• func Set(version string)
• func String() string
• type Change
  • func (c *Change) String() string

Examples

• Package

Variables

var ChangeLog []Change

ChangeLog contains the history of version changes.

var (
	// DateTimeFormat defines the format used to write the date-time of a version
	// change; the output format string.
	DateTimeFormat = time.RFC1123
)

See `go doc time.Parse` for formatting convention.

var Version struct {
	Major      uint
	Minor      uint
	Patch      uint
	Prerelease string
	Metadata   string
}

Version is the current version of the package. Use Set() or define ChangeLog to set the version.

var VersionPattern = `` /* 179-byte string literal not displayed */

VersionPattern defines the regular expression used to validate and identify the components of a semantic version string.

Source: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string

Functions

func FprintChangeLog

func FprintChangeLog(w io.Writer)

FprintChangeLog writes to given io.Writer w all of the entries in ChangeLog. Panics if any of the entries have invalid version strings.

func FprintPackageVersion

func FprintPackageVersion(w io.Writer)

FprintPackageVersion writes to given io.Writer w a descriptive version string. Includes the package name if defined in ChangeLog. Panics if any of the version components are invalid.

func IsSet

func IsSet() bool

IsSet returns true if and only if the package version has been set. The package version is considered not-set if all components are equal to their zero value.

func Parse

func Parse(version string) (major, minor, patch uint, pre, meta string)

Parse validates a semantic version string and returns each of its components. It panics if the given version string is invalid.

func ParseDate

func ParseDate(date string) *time.Time

ParseDate parses the given date-time string. It attempts every permutation of each dateFormat and timeFormat pair (in either order), returning the first successfully-parsed time.Time object. If none of the pairs are successful, each dateFormat (ignoring timeFormat) is then attempted. Finally, each of the standard formats provided by the time package are attempted.

func PrintChangeLog

func PrintChangeLog()

PrintChangeLog writes to stdout all of the entries in ChangeLog. Panics if any of the entries have invalid version strings.

func PrintPackageVersion

func PrintPackageVersion()

PrintPackageVersion writes to stdout a descriptive version string. Includes the package name if defined in ChangeLog. Panics if any of the version components are invalid.

func Set

func Set(version string)

Set sets the package version using a given semantic version string. It panics if the given version string is invalid.

func String

func String() string

String returns the semantic version string of the package. If the version has not been set, the last entry in ChangeLog is used (or panics if the last entry in ChangeLog contains an invalid version string). If ChangeLog has also not been set, an empty string is returned.

Types

type Change

type Change struct {
	Package     string
	Version     string
	Title       string
	Date        string
	Description []string
}

Change represents the details of a version change.

func (*Change) String

func (c *Change) String() string

String returns a formatted, multi-line string describing Change c.