Release policy
How PyColors ships updates across the ecosystem. Predictable releases, clear versioning, and transparent progress.
How PyColors shipsLink to section
PyColors is designed to move fast without becoming unstable.
The release model separates two things that often get mixed together:
- packages → technical versioning
- ecosystem → product progress
That separation lets PyColors publish precise package updates while communicating progress in a way customers and developers can understand.
Core idea
Packages follow technical truth. The ecosystem communicates product momentum.
Release modelLink to section
Packages
Ecosystem
Package versioningLink to section
Public packages such as @pycolors/ui follow Semantic Versioning.
MAJOR → breaking changes
MINOR → new features, backward compatible
PATCH → fixes and small improvementsExamples:
1.0.3 → bug fixes
1.1.0 → new components or backward-compatible features
2.0.0 → breaking changesPatch release
Use for bug fixes, documentation fixes, small polish, and safe internal improvements.
Source of truthLink to section
Release information is split by audience and purpose.
| Surface | Purpose |
|---|---|
| GitHub Releases | Technical release details |
CHANGELOG.md | Package-level changes generated through Changesets |
/changelog | Weekly ecosystem updates |
/roadmap | Product direction and upcoming work |
Why this split matters
Developers need precise technical changes. Customers need clear product progress. PyColors keeps both visible without mixing them.
Ecosystem releasesLink to section
The website communicates a weekly release cadence.
This includes updates across:
- PyColors UI
- Starter Free
- Starter Pro
- templates
- documentation
- patterns
- marketing pages
- platform and delivery layers
Packages ship when they are ready.
The ecosystem ships as a clear product narrative.
Technical truth stays precise. Product progress stays understandable.
Changesets workflowLink to section
All package releases follow the same operational model.
Make changes in the monorepoLink to section
Development happens in the core PyColors monorepo.
Add a changesetLink to section
Each package-level change gets a changeset with the correct release type: patch, minor, or major.
Merge to mainLink to section
Changes are reviewed and merged through the normal repository workflow.
Version and changelog are updatedLink to section
CI updates package versions and generates package-level changelog entries.
Publish and releaseLink to section
CI publishes packages and creates GitHub Releases where relevant.
Non-negotiablesLink to section
These rules keep releases predictable.
Technical rules
- development happens in the core monorepo
- public repositories are distribution surfaces
- public packages use Changesets
- breaking changes require major versions
- GitHub Releases remain technical truth
Product rules
- the website reflects product progress
- weekly releases explain ecosystem movement
- changelog entries stay readable
- roadmap updates stay transparent
- internal secrets and CI details are not exposed
Why this approachLink to section
Most projects fall into one of two release problems:
- releases are too slow, so the product feels inactive
- releases are too chaotic, so users lose trust
PyColors balances both:
- fast technical iteration at the package level
- predictable communication at the ecosystem level
This creates a release rhythm that supports both developer confidence and commercial trust.
What this guaranteesLink to section
This policy is designed to provide:
- predictable updates
- clear versioning
- no hidden breaking changes
- visible product progress
- traceable package history
- separation between technical truth and product narrative
Trust principle
A premium developer product should not only ship frequently. It should make progress easy to understand.
Public vs internalLink to section
The release model is public on purpose.
Public information includes:
- package versions
- changelog entries
- GitHub Releases
- roadmap progress
- weekly ecosystem updates
Internal information stays private:
- CI secrets
- deployment credentials
- infrastructure internals
- private operational workflows
Mental modelLink to section
Packages move with technical precision. The ecosystem moves with product clarity.