Release policy

PyColors uses two release layers on purpose:

• Packages ship with Semantic Versioning (precise + technical truth).
• The website ships weekly ecosystem releases (clear narrative + trust).

This keeps momentum high while staying accurate for developers and customers.

What should be public?

Yes — this policy should be public.

It improves trust (predictable shipping), reduces confusion (UI vs ecosystem), and makes contributions easier.

What stays private is the internal runbook (credentials, deployment secrets, and step-by-step CI ops).

Two-level versioning

1) UI library — SemVer

@pycolors/ui follows Semantic Versioning.

MAJOR (x.0.0) → breaking changes
MINOR (0.x.0) → new features (backward compatible)
PATCH (0.0.x) → fixes & small improvements

1.0.3 → patch: bug fixes, minor polish
1.1.0 → minor: new components or capabilities
2.0.0 → major: breaking API changes

Source of truth

• GitHub Releases for pycolors-ui
• CHANGELOG.md generated by Changesets

2) Ecosystem release — Weekly cadence

The website communicates a weekly release for the overall ecosystem:

• UI
• Starters (Free → Pro)
• Templates

ECOSYSTEM_RELEASE is a narrative version (weekly).
It must never block package releases.

Key idea

• Packages ship when ready
• The website ships every week with honest progress

The non-negotiables (ONE THING rules)

These are the rules that make everything else easier:

1. Development happens only in the core monorepo (pycolors).
2. Product repos are distribution surfaces (mirrors for releases + consumption).
3. All public packages use Changesets (no manual versioning).
4. GitHub Releases = technical truth.
5. Website changelog = product narrative.

Changesets workflow (minimum bar)

1) Make changes in monorepo
2) Add a changeset (patch/minor/major)
3) Merge to main
4) CI bumps version + updates changelog
5) CI publishes to npm + creates GitHub Release

Where each changelog lives

Related guides