Versioning, Publication, and Dependency Management

Semantic Versioning (SemVer)

All libraries strictly follow Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). The version number must accurately reflect the nature of changes:

• MAJOR – Incompatible API changes that require consumers to modify their code (breaking changes). Every major bump must be accompanied by a migration guide in the versions/ folder.

• MINOR – New functionality added in a backwards‑compatible manner (new components, services, or features that do not break existing public API).

• PATCH – Backwards‑compatible bug fixes, internal refactoring, performance improvements, or documentation updates that do not alter the public contract.

Pre‑release identifiers (e.g., 1.2.0-beta.1) may be used for early testing, but all stable releases must be plain semver triples. Version tags are permanently associated with a specific commit in the repository and must never be changed or reused.

Conventional Commits and Automated Changelogs

All commit messages must follow the Conventional Commits specification (type(scope): description). This enables automatic version determination and changelog generation. The permitted types include:

• feat – a new feature (triggers a MINOR bump).

• fix – a bug fix (PATCH bump).

• BREAKING CHANGE – footer or ! after the type/scope marks a major change (MAJOR bump).

• docs, style, refactor, test, chore – do not affect version.

The workspace uses a tool (e.g., standard-version, semantic-release, or a custom script) that:

• Analyses commits since the last release.

• Determines the next version number.

• Generates or updates a CHANGELOG.md for the library.

• Commits the changelog and version bump, then tags the release.

The CHANGELOG.md must be kept up‑to‑date and must clearly list breaking changes with links to the corresponding migration guides in versions/.

Peer Dependencies Management

Every library must declare its expected host framework and tooling as peerDependencies in package.json. This ensures the consuming application provides the required packages at compatible versions, avoiding duplicate or conflicting instances.

The mandatory peer dependencies and their version ranges are:

• The version ranges must be wide enough to accommodate the supported Angular versions but strict enough to prevent known incompatibilities.

• Libraries must not include @angular/core, @angular/common, or rxjs in dependencies – they are exclusively peerDependencies.

• Additional peer dependencies (e.g., @artstesh/forger for mock utilities) are allowed if the library exposes code that directly imports and re‑exports symbols from those packages. Such cases must be justified and documented.

When adding or updating a peer dependency, the library’s README must be updated to reflect any new required packages.

Internal Dependencies and Workspaces

Rules for internal dependencies:

• Keep dependencies minimal. A library should only depend on another if it genuinely needs its public API.

• Circular dependencies between libraries are strictly forbidden.

• Breaking changes in a downstream library must be carefully coordinated. If @company/filter introduces a breaking change, the PR must include migration files for @company/filter itself and, if necessary, update the consuming libraries to remain compatible.

Migration Files and Version Bumps

Every code change that affects the library’s public interface and requires client‑side modifications must be accompanied by a dedicated migration file inside a versions/ directory at the library root.

Structure:

Each file is named after the major or minor version that introduces the breaking change (e.g., v2.0.0.md, v3.1.0.md). A single migration file may cover multiple related breaking changes introduced in the same version.

The migration file must contain:

• Version header and release date.

• List of breaking changes – each with a clear title, the affected public API symbol(s), and a description of what changed.

• Step‑by‑step migration instructions – concrete code snippets showing the old usage and the new, correct usage. Where possible, provide a before/after comparison.

• Rationale – a brief explanation of why the change was necessary (e.g., performance, API consistency, adoption of signals).