Must Know: Versioning

Prerequisites

• - A release checklist tied to `/news/changelog` and `/news/migration-guide`.
• - Shared semver understanding across maintainers and reviewers.
• - A test baseline to compare pre-upgrade and post-upgrade behavior.

Step 1: Follow semantic versioning strictly

Use major for breaking changes, minor for backward-compatible additions, and patch for backward-compatible fixes.

MAJOR.MINOR.PATCH
1.0.0 -> initial stable major
1.3.0 -> backward-compatible feature release
1.3.1 -> backward-compatible fix release

Step 2: Update changelog in the same change set as version bumps

Whenever any package version changes, update `/news/changelog` in the same work item/PR for consistency and transparency.

Required release discipline:
- package.json version change present
- matching /news/changelog update present
- both merged in the same PR/work item

Step 3: Publish release notes using consistent categories

Document what changed with clear categories so consumers can assess risk quickly.

## 1.3.0
- Added: ...
- Changed: ...
- Fixed: ...
- Deprecated: ... (if applicable)
- Removed: ... (if applicable)

Step 4: Validate upgrades before merge

Run critical verification gates whenever dependency or package version changes are introduced.

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

Implementation Notes

• - For breaking changes, migration guide updates should land before or with the release.
• - Version policy should be visible in onboarding, contribution, and governance docs.
• - Never ship undocumented behavior changes in patch releases.

Troubleshooting

• - If upgrade regressions appear, compare changelog entries against observed behavior first.
• - If breaking behavior slips into minor/patch, tighten review and release gates immediately.
• - If consumers are confused, improve migration examples and release note clarity.

Next Actions