apicheck

Documentation

Overview

Package apicheck renders the exported surface of the supported packages so a change to it has to be deliberate.

The problem this exists for is not hypothetical. Over two days this repository added five methods to matching.CommandLog, changed what matching.Shards accepts, added fields to orderentry.Msg and bumped the wire protocol twice. Every one of those breaks somebody, every one was defensible on its own, and nothing in the build or the test suite said "this is a compatibility event" — the tests were updated along with the code, which is exactly what makes a break invisible.

So the surface is rendered to a golden file, the same trick internal/wire uses for the protocol. The check does not stop a breaking change. It makes one impossible to ship without a human regenerating the file and, one hopes, noticing what they are regenerating. See docs/COMPATIBILITY.md.

Index

• func Covered(root string) ([]string, error)
• func Render(root string) (string, error)

Functions

func Covered

func Covered(root string) ([]string, error)

Covered lists the package paths under pkg/ whose exported surface is frozen. Anything not here — internal/, cmd/, examples/ — carries no promise, and internal/ additionally cannot be imported.

func Render

func Render(root string) (string, error)

Render walks the covered packages and returns their exported surface, one declaration per line, sorted. The output is deliberately plain text: a diff of it should be readable in a pull request without tooling.