Must Know: Versioning

Prerequisites

• - A release checklist tied to changelog and migration docs.
• - Semver policy understood by maintainers and consumers.
• - A test baseline to compare pre/post-upgrade behavior.

Step 1: Follow semantic versioning strictly

Use major for breaking changes, minor for additive changes, and patch for fixes.

MAJOR.MINOR.PATCH
2.0.0 -> breaking change
2.1.0 -> backward-compatible feature
2.1.1 -> backward-compatible fix

Step 2: Publish change categories consistently

Every release should include Added, Changed, Fixed, Deprecated, and Removed notes where applicable.

## 1.2.0
- Added: New accessibility docs pages
- Changed: Updated initialization guidance
- Fixed: Incorrect route links in support docs

Step 3: Upgrade with verification gates

Upgrade dependencies in a branch and validate critical interaction flows before merge.

npm install @diwacopilot/components@latest
  npm test
npm run build:storefront

Implementation Notes

• - Migration guide entries should appear before or with any breaking release.
• - Version policy should be visible in onboarding and contribution docs.
• - Avoid undocumented behavioral changes in patch releases.

Troubleshooting

• - If an upgrade causes regressions, compare changelog categories first.
• - If breaking changes ship unexpectedly, tighten release review gates.
• - If consumers are confused, improve migration examples and issue templates.

Next Actions