Skip to main content

afrigov is an open-source project. It is not a government website and is not affiliated with any government.

Previewing neutral core Change

afrigov Accessible government design system

Versioning and deprecation

What a version number promises, what counts as a breaking change, and how long a deprecated thing lives.

Before 1.0

afrigov follows semantic versioning. Until 1.0, a minor version (0.3 to 0.4) may change anything, and the changelog says what. A patch version (0.4.0 to 0.4.1) never changes a class name, a token name or the pack schema. Pin to a minor, like afrigov@0.4, and read the changelog before moving.

From 1.0

These are the public surface. Changing any of them in a way that breaks a page is a major version:

  • Class names starting ag-, and the HTML structure each one expects.
  • Custom property names starting --ag-.
  • The pack schema: every field in tokens/packs/pack.schema.json.
  • The data attributes the script reads, like data-ag-toggle and data-ag-char-count.
  • The exported names of afrigov.js.
  • The published file names: core.css, <code>.css, flags/<code>.svg, afrigov.js.

These may change in a minor version, because they do not break a page that follows the documentation:

  • New classes, tokens, pack fields, components, packs and languages.
  • Visual refinements that keep contrast and target sizes: spacing, weights, radii, the exact shade of a derived colour.
  • The documentation site, the templates, the scoreboard, the build scripts.

Anything not listed above is internal and may change at any time: class names starting _ or docs-, the source layout, test files.

Deprecation

  1. A deprecated class, token or field keeps working for at least two minor versions, and for at least six months, whichever is longer.
  2. The changelog names it, says what replaces it, and gives the version it will be removed in.
  3. The documentation page shows the replacement first and the deprecated form in a note.
  4. Where the build can detect it, a pack using a deprecated field gets a warning, not an error, until removal.

Browser support

Dropping a browser the system currently supports is a major version. Adding support never is. The current list is on Get started.

Accessibility as a contract

A change that lowers contrast below AA, shrinks a target below 48px, or makes a component depend on JavaScript is treated as a breaking change even if no class name moves, because it breaks the page for someone. It will not ship in a minor version.

Releases

Every release is a git tag, a GitHub release and an npm publish with provenance from the same commit. The changelog is the record. There are no pre-releases on npm; unreleased work is on main and on the documentation site, which deploys from main.