Versioning & Contributing

Strata follows a modified semantic versioning scheme: MAJOR.FEATURE.BUGFIX. The key difference from ordinary semver — FEATURE and BUGFIX are cumulative counters, not per-release resets. They only reset back to zero when MAJOR bumps.

Segment	Meaning	Resets when…
`MAJOR`	Design era — bumped only on a fundamental, every-user-must-update change.	Never on its own — it's the thing doing the resetting.
`FEATURE`	Cumulative count of feature releases shipped since this MAJOR era began.	Only when MAJOR bumps.
`BUGFIX`	Cumulative count of bugs fixed since this MAJOR era began.	Only when MAJOR bumps.

That means 1.5.12 is readable at a glance: era 1, 5 feature releases in, 12 bugs fixed total across that whole era — not just since the last feature release.

Try it

Click commit types below to see how they move the version. Notice fix: and feat: both only ever count up — the only way either counter goes back to 0 is a BREAKING: commit, which resets both at once.

1.0.0

Commit prefix → version impact

Prefix	Version impact	Example
`feat:`	FEATURE++	`feat(select): add autoWidth option`
`fix:`	BUGFIX++	`fix(picker): correct scroll offset`
`BREAKING:`	MAJOR++ (resets FEATURE/BUGFIX)	`BREAKING: rename --st-primary tokens`
`docs:`	none	`docs: update CONTRIBUTING.md`
`refactor:`	none	`refactor(registry): simplify spacing loop`
`test:`	none	`test: add picker debug example`
`chore:`	none	`chore: update dependencies`

A MAJOR bump requires a MIGRATION.md — no exceptions

Strata won't ship a MAJOR release without a migration doc committed alongside it. If you're proposing a BREAKING: change, write the migration guide as part of the same PR, not as a follow-up.

Branch pipeline

Only four branches exist, ever: main, beta, test, dev. There are no feature/* or fix/* branches — work commits directly onto dev, and promotion flows one direction only:

dev → test → beta → main

Each arrow is a PR, never a direct push — main, beta, and test are all protected. A build check (node bin/strata.js --build) runs at every stage, and the final beta → main promotion additionally requires a review.

Pre-release tags

Only beta and main are ever published to npm — dev and test are internal integration/QA stages that never see a release.

Branch	Version format	npm tag
`dev`	—	not published
`test`	—	not published
`beta`	`1.2.3-beta.1`	`--tag beta`
`main`	`1.2.3`	`--tag latest`

npm install strata-css          # stable (latest)
npm install strata-css@beta     # beta

Package versioning is independent

Each companion package (@strata-packages/forms, @strata-packages/picker, etc.) versions on its own schedule between MAJOR releases — it only moves when it has its own changes, not because core bumped a FEATURE or BUGFIX number:

strata-css              1.1.0  →  1.2.0  →  1.3.6
@strata-packages/forms  1.0.0  →  1.1.3  →  (unchanged)
@strata-packages/picker 1.0.0  →         →  1.1.0

The one exception is a MAJOR bump: when strata-css releases 2.0.0, every package ships a matching 2.0.0 build even if unchanged, to keep its peer-dependency range — the actual compatibility contract — honest:

"peerDependencies": {
  "strata-css": ">=1.0.0 <2.0.0"
}

Full checklist and raw file

This page covers the mechanics; the complete publishing checklist, MAJOR-release requirements, and the exact commit format spec live in the Contributing policy page, rendered directly from CONTRIBUTING.md at the repo root.