compat

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2020 License: Apache-2.0 Imports: 11 Imported by: 0

README

gocompat godoc Build Status codecov.io

gocompat is a tool to check compatibility between Go API versions.

Usage

Listing all symbols

gocompat considers an API as all exported symbols in a given set of packages as well as all exported symbols reachable from them. You can check this for the current package as follows:

gocompat reach .
Compare current version against reference data

gocompat can save your API for later comparison. Usage example:

git checkout v1.0.0
gocompat save ./...
git checkout master
gocompat compare ./...
Comparing two git reference

gocompat can compare the API of two git references in a repository. For example:

gocompat compare --git-refs=v0.1.0..master ./...

Declaring your compatibility guarantees

There is almost no API change in Go that is fully backwards compatibility (see this post for more). By default, gocompat uses a strict approach in which most changes to exported symbols are considered incompatible. The --exclude= flag can be used to exclude a change type from results.

Most users will probably want to use compatibility guarantees analogous to the Go 1 compatibility promise. You can use the --go1compat for that, which is a shorthand for --exclude=TopLevelDeclarationAdded --exclude=FieldAdded --exclude=MethodAdded. For example:

gocompat compare --go1compat --from-git=v1.0.0..v1.1.0 ./...

If you are using Semantic Versioning, you might want to use the strict defaults for patch versions.

License

Released under the terms of the Apache License Version 2.0, see LICENSE.

Documentation

Index

Constants

View Source 
const (
	TypeDeclaration  DeclarationType = "type"
	AliasDeclaration                 = "alias"
	VarDeclaration                   = "var"
	ConstDeclaration                 = "const"
	FuncDeclaration                  = "func"
)
View Source 
const (
	StructType    Type = "struct"
	BasicType          = "basic"
	SliceType          = "slice"
	ArrayType          = "array"
	FuncType           = "func"
	ChanType           = "chan"
	MapType            = "map"
	PointerType        = "pointer"
	InterfaceType      = "interface"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type API 

type API struct {
	// Packages included directly in the API.
	Packages []*Package
	// Reachable is the set of all objects that are reachable from the API.
	Reachable []*Object
}

API

func NewAPI 

func NewAPI() *API

NewAPI creates an empty API.

func ReachableFromPackages 

func ReachableFromPackages(pkgs ...string) (*API, error)

ReachableFromPackages gets an API given list of package paths.

func (*API) LookupSymbol added in v0.2.0 

func (a *API) LookupSymbol(sym *Symbol) *Object

func (API) MarshalEasyJSON added in v0.2.0 

func (v API) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (API) MarshalJSON added in v0.2.0 

func (v API) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*API) UnmarshalEasyJSON added in v0.2.0 

func (v *API) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*API) UnmarshalJSON added in v0.2.0 

func (v *API) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Change 

type Change struct {
	Type   ChangeType
	Symbol string
}

func Compare 

func Compare(a, b *API) []Change

func CompareObjects 

func CompareObjects(a, b *Object) []Change

CompareObjects compares two objects and reports backwards incompatible changes.

func (Change) String 

func (c Change) String() string

type ChangeType 

type ChangeType int
const (

	// PackageDeleted means that a package that was added explicitly to the API
	// was deleted. This is not used when a package that is reachable but not
	// explicitly added to the API is deleted. In that case, a package deletion
	// would be seen as type changes that render the package not reachable
	// anymore.
	PackageDeleted ChangeType

	// TopLevelDeclarationAdded means that a top-level declaration was added to
	// a package. This can be either a type, var, const or func. It does not
	// include method declarations.
	TopLevelDeclarationAdded

	// TopLevelDeclarationDeleted means that a top-level declaration is deleted
	// from a package. It does not include method declarations.
	TopLevelDeclarationDeleted

	// DeclarationTypeChanged means that the type of declaration changed. For
	// example, a declaration changed from being a var to a const. Note that
	// changing between type definitions and type aliases is covered here too.
	DeclarationTypeChanged

	// TypeChanged means that an entity (type declaration, field, parameter,
	// return type) has changed its type.
	//
	// This does not cover when there is a change in the type underlying a type
	// name. For example, TypeChanged will be signaled if a var changes from
	// MyTypeA to MyTypeB, but it will not if MyType itself changes from being
	// a struct to an interface.
	//
	// A change in the direction of a channel is also considered a type change.
	//
	// See https://golang.org/ref/spec#Types
	TypeChanged

	// FieldAdded means that a new exported field was added to a struct.
	FieldAdded

	// FieldDeleted means that a previously exported field was deleted from a
	// struct.
	FieldDeleted

	// FieldChangedType means that a field in a struct changed its type.
	// See TypeChanged.
	FieldChangedType

	// SignatureChanged means that a function declaration changed its signature.
	SignatureChanged

	// MethodAdded means that a new exported method declaration was added.
	MethodAdded

	// MethodDeleted means that a previously exported method declaration was
	// deleted.
	MethodDeleted

	// MethodSignatureChanged means that the signature of a method has changed.
	// Receiver name, parameter names and return type names are ignored.
	MethodSignatureChanged

	// InterfaceChanged means that any function, exported or not, was added,
	// deleted or had its signature changed.
	InterfaceChanged
)

func ChangeTypeFromString 

func ChangeTypeFromString(s string) (ChangeType, error)

ChangeTypeFromString converts a string representation of the ChangeType to its numeric value.

func (ChangeType) String 

func (i ChangeType) String() string

type DeclarationType added in v0.2.0 

type DeclarationType string

type Definition added in v0.2.0 

type Definition struct {
	Type      Type          `json:"type"`
	Symbol    *Symbol       `json:"symbol,omitempty"`
	Elem      *Definition   `json:"elem,omitempty"`
	Key       *Definition   `json:"key,omitempty"`
	Len       int64         `json:"len,omitempty"`
	ChanDir   types.ChanDir `json:"chandir,omitempty"`
	Fields    []*Field      `json:"fields,omitempty"`
	Functions []*Func       `json:"functions,omitempty"`
	Signature *Signature    `json:"signature,omitempty"`
}

func (Definition) MarshalEasyJSON added in v0.2.0 

func (v Definition) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Definition) MarshalJSON added in v0.2.0 

func (v Definition) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Definition) UnmarshalEasyJSON added in v0.2.0 

func (v *Definition) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Definition) UnmarshalJSON added in v0.2.0 

func (v *Definition) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Field added in v0.2.0 

type Field struct {
	Name string
	Type *Definition
}

func (Field) MarshalEasyJSON added in v0.2.0 

func (v Field) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Field) MarshalJSON added in v0.2.0 

func (v Field) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Field) UnmarshalEasyJSON added in v0.2.0 

func (v *Field) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Field) UnmarshalJSON added in v0.2.0 

func (v *Field) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Func added in v0.2.0 

type Func struct {
	Signature
	Name string
}

func (Func) MarshalEasyJSON added in v0.2.0 

func (v Func) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Func) MarshalJSON added in v0.2.0 

func (v Func) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Func) UnmarshalEasyJSON added in v0.2.0 

func (v *Func) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Func) UnmarshalJSON added in v0.2.0 

func (v *Func) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Object added in v0.2.0 

type Object struct {
	Symbol     Symbol          `json:"symbol"`
	Type       DeclarationType `json:"type"`
	Definition *Definition     `json:"definition,omitempty"`
	Methods    []*Func         `json:"methods,omitempty"`
}

func ConvertObject added in v0.2.0 

func ConvertObject(obj types.Object) *Object

func (Object) MarshalEasyJSON added in v0.2.0 

func (v Object) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Object) MarshalJSON added in v0.2.0 

func (v Object) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Object) UnmarshalEasyJSON added in v0.2.0 

func (v *Object) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Object) UnmarshalJSON added in v0.2.0 

func (v *Object) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Package added in v0.2.0 

type Package struct {
	Path    string             `json:"path"`
	Objects map[string]*Object `json:"objects"`
}

func NewPackage added in v0.2.0 

func NewPackage(path string) *Package

func (Package) MarshalEasyJSON added in v0.2.0 

func (v Package) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Package) MarshalJSON added in v0.2.0 

func (v Package) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Package) UnmarshalEasyJSON added in v0.2.0 

func (v *Package) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Package) UnmarshalJSON added in v0.2.0 

func (v *Package) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Signature added in v0.2.0 

type Signature struct {
	Params   []*Definition
	Results  []*Definition
	Variadic bool
}

func (Signature) MarshalEasyJSON added in v0.2.0 

func (v Signature) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Signature) MarshalJSON added in v0.2.0 

func (v Signature) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Signature) UnmarshalEasyJSON added in v0.2.0 

func (v *Signature) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Signature) UnmarshalJSON added in v0.2.0 

func (v *Signature) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Symbol added in v0.2.0 

type Symbol struct {
	Package string `json:"package"`
	Name    string `json:"name"`
}

func (Symbol) MarshalEasyJSON added in v0.2.0 

func (v Symbol) MarshalEasyJSON(w *jwriter.Writer)

MarshalEasyJSON supports easyjson.Marshaler interface

func (Symbol) MarshalJSON added in v0.2.0 

func (v Symbol) MarshalJSON() ([]byte, error)

MarshalJSON supports json.Marshaler interface

func (*Symbol) UnmarshalEasyJSON added in v0.2.0 

func (v *Symbol) UnmarshalEasyJSON(l *jlexer.Lexer)

UnmarshalEasyJSON supports easyjson.Unmarshaler interface

func (*Symbol) UnmarshalJSON added in v0.2.0 

func (v *Symbol) UnmarshalJSON(data []byte) error

UnmarshalJSON supports json.Unmarshaler interface

type Type added in v0.2.0 

type Type string

Source Files

View all Source files

Directories

Path Synopsis
cmd
gocompat

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.