🚀 Semantic Versioning (SemVer) Guide

Ever wondered how developers keep track of changes across versions without losing their minds? 😅 This guide breaks down Semantic Versioning (SemVer) into simple, practical rules you can follow every day.

📘 Overview

• SemVer follows MAJOR.MINOR.PATCH.
• MAJOR → Breaking changes (🚨 not backward compatible).
• MINOR → New, backward-compatible features (✨ additions).
• PATCH → Backward-compatible bug fixes (🛠️ small fixes).
• Pre-release tags like -alpha or -beta mark unstable builds, while metadata (+build.5) adds info without changing ordering.

🏗️ Current Versioning Scheme

• Current tag: 0.1.0-alpha
• 0 → Not production-stable yet.
• 1 → First milestone with basic functionality.
• alpha → Limited testing/instability; upgrade to beta as confidence grows.

🧭 Source of Truth

• Keep the canonical version in package.json ("version": "0.1.0-alpha").
• Use `.env` for overrides (APP_VERSION=0.1.0-alpha) — Expo reads this first.
• In app.config.js, Expo loads dotenv and exposes the version via extra.appVersion.
• UI surfaces (e.g. profile.tsx) read from runtime constants to match release data shown to users.

🏷️ Releasing & Tagging

• Bump the version before distributing (TestFlight, Play, QA, production).
• Flow: update package.json → build → commit → tag (git tag v0.1.0-alpha) → push (git push origin v0.1.0-alpha).
• Tags are immutable markers — perfect for changelogs, pipelines, or historical tracking.

📈 When To Increment

• Everyday dev: no bump needed until release prep.
• Pre-release cadence:
  • 🐞 Bug fixes → 0.1.1-alpha
  • ✨ New features → 0.2.0-alpha (or -beta if stability improves)
  • 💥 Breaking changes → bump MAJOR (after 1.0)
• Progress tags as stability increases → -alpha → -beta → final release.

🧩 Best Practices

• Keep package.json as your single source of truth 🧠.
• Document release notes with exact version tags (GitHub Releases work great).
• Automate version bumps using tools like npm version, Changesets, or custom scripts.

🎉 In short: SemVer keeps your project predictable, your collaborators aligned, and your releases clean. Follow these principles, and you’ll never lose track of what’s changed — or why.