Changelog and Versioning Policy¶

Versioning Scheme¶

All four packages (@cyber-eco/types, @cyber-eco/firebase, @cyber-eco/auth, @cyber-eco/services) share the same version number at all times. This is enforced by Changesets' fixed mode.

When any package changes, all packages get the same version bump.

Why Fixed Versioning¶

The four packages form a tight dependency chain. A change to @cyber-eco/types (e.g., adding a field to SharedUserProfile) may affect all downstream packages. Fixed versioning eliminates the compatibility matrix problem: consumers always install @cyber-eco/*@0.3.0 and know all packages work together.

Semantic Versioning¶

We follow SemVer 2.0:

PATCH (0.1.x): Bug fixes, documentation updates, internal refactoring with no API changes
MINOR (0.x.0): New functions, new interfaces, new optional fields on existing interfaces, new exports
MAJOR (x.0.0): Breaking changes — removed exports, changed function signatures, renamed interfaces, changed required fields

Pre-1.0 Policy¶

While the version is 0.x.y: - Minor versions MAY contain breaking changes (with documentation) - This signals that the API is still stabilizing - Consumers should pin to exact versions or use ~ ranges

Post-1.0 Policy (future)¶

After 1.0.0: - Breaking changes require a major version bump - Deprecated features must be maintained for at least one minor version before removal - Migration guides must accompany every major version

Release Workflow¶

Creating a Changeset¶

When you make a change that should appear in the changelog:

npx changeset

This interactive CLI asks: 1. Which packages changed? (Select one or more) 2. What kind of change? (patch / minor / major) 3. Summary of the change (this becomes the changelog entry)

The command creates a markdown file in .changeset/ (e.g., .changeset/happy-dogs-sleep.md).

Versioning¶

When changesets are merged to main, the GitHub Action creates a "Version Packages" PR that: 1. Bumps all package versions according to the accumulated changesets 2. Updates all CHANGELOG.md files 3. Updates all internal workspace:* dependency references

Publishing¶

When the "Version Packages" PR is merged: 1. The GitHub Action builds all packages 2. Runs all tests 3. Publishes to GitHub Packages 4. Creates a GitHub Release with the changelog

Pre-release Versions¶

For testing before a final release:

npx changeset pre enter alpha
npx changeset version
# Produces @cyber-eco/types@0.2.0-alpha.0

Consumers can test against the alpha:

npm install @cyber-eco/types@0.2.0-alpha.0

Changelog Format¶

Each package maintains a CHANGELOG.md following Keep a Changelog format:

# @cyber-eco/types

## 0.2.0

### Minor Changes
- Added `Friendship` interface to shared types
- Added `PermissionCondition` for conditional access
- Enhanced `GroupMember.role` with 4-tier hierarchy (owner/admin/moderator/member)

### Patch Changes
- Fixed `HubUser.preferences.theme` type to use 'system' instead of 'auto'

Commit Convention¶

Commits should follow Conventional Commits:

feat(types): add Friendship interface
fix(firebase): handle lazy initialization in adapter
docs(architecture): add collection schema table
refactor(services): extract NotificationService from SharedDataService
test(services): add DataLayerService orchestration tests
chore: update turbo to 2.3.1

The scope should match the package name (types, firebase, auth, services) or be omitted for cross-cutting changes.