Should API style guide rules block a release?

A few of them should, and the test is what happens downstream when the rule is violated. A duplicate operation identifier produces generated clients that do not compile, so blocking is proportionate. A missing tag description costs a reader a moment, so blocking is not. Most guides end up with a handful of blocking rules and are stronger for it.

What is the difference between an error and a warning in an API linter?

They are promises about what happens to the person who hits them. An error says this does not ship, so somebody has to stop and fix it now. A warning says fix this while you are here, so it gets reported and never interrupts. Using error for things you do not actually intend to block is what teaches people to ignore the output.

How do you handle a rule that a legacy API cannot satisfy?

Scope the exception rather than change the standard. Override the rule for the one project that cannot meet it and leave the organisation default where it is, so the remaining rules still apply to that project and the standard still applies everywhere else. An exception with a reason attached is governance working, and a lowered standard is governance losing.

Where should API governance rules be enforced?

Continuously while somebody edits, and as a gate when a version is released. Editing is where a violation is cheapest to fix, because the author is still in the file. The release is the last point where blocking is fair, since the work is finished and the fix is visible. Blocking every save teaches people to work around the tool instead.

Severity and Enforcement

A severity looks like a property of a rule. It is actually a sentence about what happens to a person, and that is the only way to choose it correctly.

Three severities are three promises

Before assigning any of them, it is worth saying out loud what each one commits you to.

Each severity is a promise about somebody's next ten minutes. Info costs a glance and never interrupts. Warning asks for a fix while the author is already in the file. Error stops the release, which means somebody stops what they were doing, so it has to be worth an interruption every single time it fires.

Info means the guide has an opinion and will not insist. It is the right level for a rule you are still socialising and for one that depends on the API.

Warning means fix it while you are here. Most naming and completeness rules belong at this level for their entire life, and that is a stable state rather than a failure.

Error means this does not ship. Somebody stops, and the rule has to be worth that interruption on every occasion it fires, including the inconvenient ones.

The fourth option is off, and switching a rule off after looking at it is a legitimate outcome. An enabled rule everybody has learned to scroll past costs the same attention on every run and buys nothing, while teaching the team that findings are background texture.

The name of a rule is not its severity

Rules tend to be written in the imperative, so a list of them reads like a list of requirements.

A rule called Operations must have a description is a warning in most organisations, and there is nothing inconsistent about that. The wording describes the convention, and the severity describes your enforcement appetite. Reading a rules table as a list of things that will stop a release is a common way to overestimate what a guide is doing.

Say this explicitly when you introduce a guide to a team, because the alternative is people assuming the worst and asking for the whole thing to be turned off.

Where the block lands decides whether it is fair

A blocking rule is tolerable when the person who hits it can fix it right there. It is resented when they cannot.

Blocking on every save is the worst arrangement, since it interrupts the work at the exact moment the document is legitimately incomplete. Half-written is a normal state for a specification, and a tool that refuses to accept it teaches people to draft somewhere else.

Blocking at the release is the arrangement that holds. The work is finished, the author is the person who can fix it, and the cost of the rule is paid once rather than continuously. It is also the last moment where a fix is cheaper than a migration.

An escape hatch is what keeps the guide on

Every guide meets an API it cannot fit. What happens next decides whether the guide survives that meeting.

A guide with no exception mechanism does not produce compliant APIs, it produces teams that stop running the guide. An exception that is scoped and written down does the opposite, because the rest of the standard still applies to that project and everybody can see what was agreed.

The rule of thumb is that an exception should name a project rather than lower a default, carry a reason, and be something a person could review later. An organisation that cannot name its exceptions does not know what its standard is.

The two numbers that say the guide is failing

You can tell whether a guide is working from the shape of its output rather than from its contents.

If the violation count only grows, nothing is ever being fixed, which means every rule is advisory in practice and the guide is a report. If almost every rule is an error, people are either blocked constantly or bypassing the check, and both end with the guide switched off.

A healthy guide has a small blocking set that fires rarely, a larger advisory set that trends downward, and a handful of rules somebody deliberately turned off.

In Routebase

Severity is set per rule, and the rules and the blocking are separate switches.

The General card of the style guide settings page, with a Style Guide toggle described as enabling automated design governance and a separate Enforce on Publish toggle described as blocking publishing for API versions with error-level violations, both switched on. — Enforcement is its own switch, so the rules can run and report for as long as you need before anything stops a publish.

Every rule sits at error, warning, info or off, and a rule you changed from its default carries an override badge with a one-click reset. Enforcement on publish is off until somebody turns it on, so switching the guide on does not by itself stop a release.

With enforcement on, error-level violations block a publish and the dialog says how many have to be fixed. Warnings never block, and they can be published after a confirmation, which keeps the difference between the two severities visible at the moment it matters.

Exceptions are scoped by project. The organisation sets the standard, and a project can override the severity of any rule for its own specifications. The project view adds a source column reading custom, org or default, with a reset back to the inherited value. The Style Guide guide covers the severities, the override badge and the publish gate, and rolling governance out covers the order to turn them on in. The API governance page shows the same cascade from the organization to a project in one view.