Change packages

A change package is a YAML file that describes one API change, so that the backend and the web team can agree on it without a handoff document. It lives in the same repository as the code, and it is written by Getman, not typed by hand.

What a change package contains

Each package holds the contract diff between the last published API and the current one, request and response examples, migration notes for consumers, evidence from real runs, and each consumer’s integration status.

Files in the workspace

getman/
  contracts/openapi.yaml          the current API contract (OpenAPI 3.1)
  changes/GT-SHOP-001.yaml        one file per change package

The reference GT-SHOP-001 is an example. The ID has the form GT-<KEY>-<NNN>. The key comes from the project name (letters and digits only, upper case, at most 12 characters), or from a changeKey setting. The number is the highest existing number for that key plus one, and at least three digits. Secrets are never written to these files.

Main fields

Field	Meaning
id	The change reference, such as GT-SHOP-001.
title, summary, migration	What changed, and what consumers must do. The migration text is the part the web team reads first.
state	draft, published or withdrawn. New packages start as drafts.
author	kind (human or agent), name and optional tool. Names are informational. They do not grant permissions.
endpoints	Affected operations, such as GET /orders/{id}.
contract.base and contract.head	The revision (a SHA-256 hash of the normalized contract) before and after the change.
contract.changes	Structured diff entries, each with a kind, a location, before and after values, and a severity.
severity	The highest severity in the diff: breaking, potentially-breaking, non-breaking or unknown.
evidence	Entries from real runs. Only Getman writes them.
integrations	One entry per consumer, with status set to pending, in-progress, reported, verified or blocked.

Change states

States move with the buttons in a change’s header in the desktop app, with getman change state, or with the MCP update_change tool. Withdrawn changes leave consumers’ inboxes.

Transition	Desktop button	CLI
Draft to published	Publish	getman change state <ID> published
Published to withdrawn	Withdraw	getman change state <ID> withdrawn
Withdrawn to published	Publish again	getman change state <ID> published
Published or withdrawn to draft	Back to draft	getman change state <ID> draft

Verification labels

The label shown next to a change is calculated from its evidence. It is never stored.

Label	When it applies
Not tested	No evidence.
Documented	No evidence, but every endpoint has a description and an example.
Schema validated	The latest run matched the response schemas, and no tests are defined.
Tests passed	The latest run against the head contract passed all tests and schema checks.
Tests failed	The latest run has a failure.
Integration reported	A consumer set its status to reported.
Integration verified	A consumer set its status to verified, with a passing run of its own.

Evidence recorded against an older contract revision is marked stale. The label still shows, with the stale flag.

Evidence

Each evidence entry records the time, the tool that ran it (desktop, CLI or MCP, with its version), the environment name and kind, the contract revision that was checked, the requests run, the test results, the schema checks and the totals. All text is redacted before it is written.

Evidence comes only from a real run. To create it, use Verify now in the desktop app, getman change verify, or the MCP verify_change tool. Failing runs are recorded too.

Git rules

• Getman uses your installed Git, with your own credentials and SSH keys. It never prompts for a password.
• Nothing is committed, pushed or pulled without an explicit action.
• git pull runs with --ff-only. A diverged branch is reported, and Getman does not merge it.
• When a file changed both locally and in the folder, it is listed as a conflict for you to resolve.
• A file that still contains conflict markers, or invalid YAML, is refused with its path and a hint.
• Two clones can create the same number. Getman shows the duplicate as a conflict. Renumbering is manual: change id, rename the file to match, and commit.

Limits

• A change does not rewrite references to its old ID. Check related fields, commit messages and other files after a renumber.
• The author name is not read from Git configuration.
• Migration and summary text is plain text in the desktop app.

For the step-by-step handoff between backend and web, see the team workflow. For the commands, see the CLI reference, and for agent access, see the MCP server.