Versioning policy · Docs

ReferenceVersioning policy

Why versioning mattersLink to section

PyColors uses Semantic Versioning to make upgrades predictable, safe, and easy to understand.

A version number should immediately communicate:

the level of change
upgrade risk
compatibility expectations
migration requirements

This policy exists to reduce uncertainty across the ecosystem.

Core principle

Developers should be able to understand upgrade impact before reading the changelog.

Semantic Versioning baselineLink to section

PyColors packages, starters, templates, and shared tooling follow Semantic Versioning.

semver.txt

MAJOR.MINOR.PATCH

Patch

Fixes, polish, documentation updates, dependency-safe maintenance, and small UX improvements with no breaking changes.

Minor

New capabilities, APIs, patterns, workflows, or components that remain backward compatible.

Major

Breaking changes requiring migration, architecture updates, or incompatible API changes.

Release type rulesLink to section

Patch release

Patch releases improve stability, polish, and maintainability without changing expected integrations or workflows.

bug fixes
documentation improvements
small UI polish
dependency-safe maintenance
performance optimizations

Example: 1.0.4 → 1.0.5

Practical interpretationLink to section

In practice, the version type answers one question:

Can the user upgrade safely without migration?

Situation	Release type
Fixing bugs or polish	Patch
Adding backward-compatible capabilities	Minor
Requiring migration or changing compatibility	Major

Important distinction

A large amount of work does not automatically mean a major release. The determining factor is compatibility impact.

What is not a major releaseLink to section

The following changes usually remain patch or minor releases:

visual polish
documentation restructuring
internal refactors
performance improvements
new optional APIs
new starter sections
additive design system improvements

A release becomes major only when compatibility expectations change.

Versioning goalsLink to section

This policy is designed to provide:

predictable upgrades
transparent compatibility expectations
stable package consumption
clear migration boundaries
safer long-term adoption
stronger developer trust

Trust principle

Stable versioning is part of the product experience, not only a technical detail.

Relationship with ecosystem releasesLink to section

Semantic Versioning applies to technical package releases.

The broader PyColors ecosystem communicates progress separately through:

weekly releases
changelog updates
roadmap progression
ecosystem announcements

This separation keeps technical truth precise while making product progress easier to follow.

Source of truthLink to section

Surface	Purpose
GitHub Releases	Technical release details
`CHANGELOG.md`	Package-level changes
`/changelog`	Ecosystem progress
`/roadmap`	Upcoming direction

Release policyUnderstand how PyColors ships updates across the ecosystem.ChangelogFollow ecosystem progress and release cadence.RoadmapSee what is planned next across the platform.UI docsExplore the PyColors design system and components.