ConsensysConsensys/linea-monorepo/.cursor/rules/versioning-guidelines/RULES.md

linea-monorepo / versioning-guidelines

Cursor rule126 starsChanged 3 months agoApache-2.0View on GitHub

API and Asset Versioning - Rules for backwards compatibility

We split this RULES.md into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Create a new versioned method when introducing breaking changes to a public API consumed by another component.
line 15
Very specific:
Create a new versioned asset (e.g.
line 17
Very specific:
Use simple incremental version suffixes per method/asset (V1, V2, V3), similar to Ethereum Engine API conventions (engine_getPayloadV1 ...
line 18
Distinctive:
When a PR modifies a public API signature or overwrites an existing versioned asset, flag the change and ask:
line 37
Distinctive:
If yes, has a new versioned method/asset been created instead of modifying the existing one?
line 39

≈ “Common” is an estimate: at least 1 in 5 of the 6,350 Cursor rule files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

RULES.md

API and Asset Versioning Rules

Components must maintain backwards compatibility, especially those already released beyond devnet (sepolia, external partners). This is critical for Lineth Stack/Enterprise, where components (e.g. coordinator, contracts, tracing modules) must coexist across multiple versions.

Refer to EXAMPLES.md for detailed do/don't examples.

MUST

Create a new versioned method when introducing breaking changes to a public API consumed by another component. The existing method must remain functional so consumers can migrate on their own schedule.
Mark the old method as deprecated with a pointer to the new version.
Create a new versioned asset (e.g. LinethRollupV7.abi, LinethRollupV8.abi) instead of overwriting an existing one.
Use simple incremental version suffixes per method/asset (V1, V2, V3), similar to Ethereum Engine API conventions (engine_getPayloadV1 ... engine_getPayloadV5).
Bump the version number when a breaking change is introduced to that specific method or asset - not when unrelated parts of the system change.

MUST NOT

Refactor, rename, or change the signature of an existing public API method in a way that breaks current consumers.
Override or replace a versioned asset (e.g. ABI file) that is already deployed and consumed by external partners or environments beyond devnet.
Tie method/asset version numbers to an unrelated release train (e.g. linea-besu-package versions) - components are independently versioned.

Scope

These rules apply when:

The component is released on any environment other than devnet (sepolia, mainnet, external partners).
The public API or asset is consumed by another component or external integrator.

For internal-only, devnet-only code with no external consumers, lighter versioning practices are acceptable.

Enforcement

When a PR modifies a public API signature or overwrites an existing versioned asset, flag the change and ask:

Is this method/asset consumed by another component or external partner?
If yes, has a new versioned method/asset been created instead of modifying the existing one?
Is the old version deprecated with a pointer to the new one?

Block the change if the answer to (1) is yes and (2) or (3) is no. Reference EXAMPLES.md for correct patterns.

Download now (ZIP)

Where files are headingNew Cursor rule files have more rules about planning and tracking tasks, and fewer about code style.
Of the Cursor rule files we read, the 3,978 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- contracts/AGENTS.mdAGENTS.md
- coordinator/AGENTS.mdAGENTS.md
- e2e/AGENTS.mdAGENTS.md
- maru/AGENTS.mdAGENTS.md
- postman/AGENTS.mdAGENTS.md
- prover/AGENTS.mdAGENTS.md
- prover-ray/AGENTS.mdAGENTS.md
- tracer/AGENTS.mdAGENTS.md
- transaction-exclusion-api/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/documentation.mdcCursor rule
- .cursor/rules/security-logging-guidelines/EXAMPLES.mdCursor rule
- .cursor/rules/security-logging-guidelines/RULES.mdCursor rule
- .cursor/rules/smart-contract-guidelines/RULE.mdCursor rule
- .cursor/rules/versioning-guidelines/EXAMPLES.mdCursor rule
- developing-smart-contractsSkill
- linea-dependency-maintenanceSkill
- squash-bugbotSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free