vers

README

vers

semantic versioning for plugins

Documentation

Overview

Package vers models semantic versioning for a runtime / plugin system.

The system should be Forwards Compatible within Minor and Patch versions.

A runtime calls a plugin passing in Config and expecting to receive Results. A single Spec defines the data types and behavior for Config and Results, but the Spec may evolve over time and be versioned.

Breaking changes to the Spec, such as removal of a field from either the Config or Results, should cause a Major version bump. Adding a field to either Config or Results should cause a Minor version bump.

Any given plugin will require Config at a particular Semantic Version. This means that if the runtime provides Config with greater Minor (or Patch) versions (but with equal Major versions) then the plugin should work.

Similarly, if the plugin provides a Result with a Minor (or Patch) version higher than that required by the runtime, then the runtime should be able to accept that data (again given equality of Major version numbers)

Plugins are assumed to be lightweight but a runtime may support many Modes, each of which could drive plugins at a single Major version.

Index

• Variables
• func Check(runtime RuntimeMode, plugin Plugin) error
• type Plugin
• type RuntimeMode

Variables

var ErrorIncompatible = errors.New("incompatible versions")

Functions

func Check

func Check(runtime RuntimeMode, plugin Plugin) error

Check returns nil if the given RuntimeMode is compatible with the given Plugin. Otherwise it returns an error.

Semantic versioning applies, so Major version differences always cause an error. Minor and patch version differences are allowed if and only if the provider version meets or exceeds the required version.

Types

type Plugin

type Plugin struct {
	RequiresConfig  semver.Version
	ProvidesResults semver.Version
}

Plugin represents the required version of input Config and provided version of output Results for a single plugin.

type RuntimeMode

type RuntimeMode struct {
	ProvidesConfig  semver.Version
	RequiresResults semver.Version
}

RuntimeMode represents one (of possibly several) modes of operation of the runtime. If one mode fails to check against a plugin, then the runtime may opt to fall back to an older mode which does check ok.