A-12: `pkg/gopass` API Stability Contract

Status: accepted
Source: GitHub Issue #3414

Background

ARCHITECTURE.md (lines 37–43) documents that gopass applies semantic versioning to the CLI tool only, not the Go module. pkg/gopass is the documented integration point for external consumers (gopass-hibp, gopass-jsonapi, git-credential-gopass, gopass-summon-provider, and others). There is currently no documented contract for what constitutes a breaking change or how consumers will be notified.

A breaking change to pkg/gopass.Store, pkg/gopass.Secret, or related types can affect consumers silently — the module version does not increment, no changelog entry was mandated, and go get would pull the break without warning.

Decision

Implement Options B and C. They are complementary and together give consumers both runtime/source-level signals (C) and a reliable notification channel (B).

Option A (full module semver / v2 path) is deferred — the current team size makes the coordination overhead infeasible.

Option D (separate repository) is deferred for the same reasons.

Option B — "Best-effort stable" policy with mandatory changelog tags

Policy

pkg/gopass and its sub-packages are declared best-effort stable:

Additive changes (new exported symbols, new optional parameters via functional options) may appear in any release without prior notice.
Breaking changes (removal or signature change of an exported symbol, change of error semantics, change of an interface method set) require:
1. A [PKG-BREAK] entry in the ## Next section of CHANGELOG.md describing what changed and how consumers should migrate.
2. A minimum deprecation window of two minor releases or three months, whichever is longer, between the first deprecation notice and removal. During this window the old symbol must remain available (possibly with a // Deprecated: GoDoc comment pointing to the replacement).

Changelog tag convention

Breaking changes to pkg/ are tagged [PKG-BREAK] in CHANGELOG.md:

[PKG-BREAK] pkg/gopass: Remove Store.GetRevision — use Store.History instead (deprecated since 1.17.0)

The existing helpers/changelog generator reads CHANGELOG.md verbatim; no changes to that tool are needed. The [PKG-BREAK] tag is a pure text convention, consistent with existing tags such as [SECURITY], [BUGFIX], and [FEATURE].

Enforcement

Code reviewers must reject PRs that remove or change exported pkg/ symbols without a corresponding [PKG-BREAK] changelog entry and a prior deprecation notice.
The golangci-lint godot and godox rules already catch missing doc-comment periods and stray TODO/FIXME markers; no additional tooling is introduced.

Option C — Explicit stability annotations in package doc comments

Each package under pkg/gopass/ carries a doc comment that states its stability level.

Package	Level	Rationale
`pkg/gopass`	best-effort stable	Core interfaces; multiple known consumers
`pkg/gopass/api`	best-effort stable	Primary API implementation
`pkg/gopass/secrets`	best-effort stable	Secret types consumed by integrations
`pkg/gopass/apimock`	testing helper — no stability guarantee	Internal test double; consumers should copy or vendor it

The standard // Deprecated: GoDoc convention is used to signal pending removal of individual symbols; godoc and pkg.go.dev render these prominently.

Affected packages

pkg/gopass/, pkg/gopass/api/, pkg/gopass/apimock/, pkg/gopass/secrets/

Consequences

External integrators get a documented, reasonable stability promise without requiring a module-path change today.
The changelog [PKG-BREAK] tag gives integrators a single place to scan for migration work when upgrading.
The deprecation window gives integrators time to adapt before a symbol is removed.
The policy can be upgraded to full module semver in the future if maintainer capacity grows, without breaking any existing convention.

4.1 KiB Raw Permalink Blame History Unescape Escape

A-12: pkg/gopass API Stability Contract