Claude Code के साथ सुरक्षित Changesets Versioning

Claude Code release काम को तेज कर सकता है, लेकिन package version को बिना नियमों के AI पर छोड़ना खतरनाक है। अगर breaking change को patch की तरह publish कर दिया गया, तो users के builds टूट सकते हैं। अगर internal package गलती से npm पर publish हो गया, तो उसे साफ करना मुश्किल होता है। Changesets इस समस्या को इसलिए कम करता है क्योंकि हर PR में release intent लिखा जाता है: कौन सा package बदला, कौन सा bump चाहिए, और क्यों।

इस guide में Claude Code और Changesets का practical workflow है: SemVer basics, package release notes, monorepo packages, private/internal packages, GitHub Actions release flow, npm publish risk, CHANGELOG quality, और AI-generated गलत version bumps से बचने के prompts। Official references के लिए SemVer, Changesets, npm publishing docs, और GitHub Actions docs देखें। Related ClaudeCodeLab articles: CLAUDE.md best practices, CI/CD setup, और monorepo management।

पहले SemVer साफ करें

SemVer का मतलब semantic versioning है। 1.4.2 में format major.minor.patch होता है। patch bug fix है जो public contract नहीं बदलता। minor backward-compatible feature है। major वह change है जिससे users को अपना code बदलना पड़ सकता है।

Public contract सिर्फ function name नहीं होता। React props, CSS tokens, CLI flags, exit codes, default behavior, और exported TypeScript types भी contract का हिस्सा हैं। Claude Code को prompt में यह rule दें, नहीं तो वह diff के size या commit message से गलत bump चुन सकता है।

Practical use cases:

Use case	Risk	Claude Code क्या review करे
UI package	props, variants, CSS tokens, peer dependencies	bump public API change से match करता है या नहीं
CLI package	flags, command names, exit codes	README, tests और code aligned हैं या नहीं
Monorepo	internal dependency ranges	dependent package को भी release चाहिए या नहीं
Internal package	accidental npm publish	private, ignore, registry और token settings

Initial setup

Changesets install और initialize करें।

npm install -D @changesets/cli @changesets/changelog-github
npx changeset init

.changeset/config.json के लिए यह अच्छा starting point है:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

fixed उन packages का group है जो हमेशा same version पर रहेंगे। linked related packages को साथ bump करता है, लेकिन उनके version numbers अलग रह सकते हैं। updateInternalDependencies workspace dependency ranges को update करने का rule है। Monorepo में local build workspace:* से pass हो सकता है, लेकिन published users के लिए range गलत हो तो install fail हो सकता है।

Common scripts रखें:

{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status --since=origin/main",
    "version": "changeset version",
    "release": "changeset publish",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run"
  }
}

changeset लिखना

जब PR public package contract बदलता है, यह चलाएं:

npx changeset

Example:

---
"@myapp/ui": minor
"@myapp/utils": patch
---

Add the `outline` variant to Button and keep the existing `solid` and `ghost` variants compatible.

Fix `formatCurrency` so it handles zero-decimal currencies without rounding errors.

@myapp/ui में backward-compatible option जोड़ा गया है, इसलिए minor। @myapp/utils में existing function fix है, इसलिए patch। अगर prop हटाया गया, CLI flag rename हुआ, या default behavior बदला, तो उसे major candidate मानें।

Claude Code prompt:

Current PR diff पढ़कर Changesets changeset draft करें।

Rules:
- SemVer follow करें: breaking change major, backward-compatible feature minor, fix patch
- package.json version सीधे edit न करें
- npm publish न चलाएं
- private: true packages को publish plan में शामिल न करें

Return:
- changed packages
- हर package के लिए recommended bump
- reasoning
- proposed .changeset/*.md content
- uncertain points for human review

Monorepo और internal packages

Real repository में publishable packages और deploy-only apps साथ होते हैं। Example: @myapp/ui npm पर publish होता है, लेकिन @myapp/app सिर्फ web app deploy है।

{
  "name": "@myapp/app",
  "private": true,
  "version": "0.0.0",
  "scripts": {
    "build": "next build"
  },
  "dependencies": {
    "@myapp/ui": "workspace:*"
  }
}

Changesets config में ignore:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [
    ["@myapp/core", "@myapp/cli"]
  ],
  "linked": [
    ["@myapp/ui", "@myapp/theme"]
  ],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myapp/app", "@myapp/docs"]
}

Internal registry के लिए registry explicit रखें:

{
  "name": "@my-company/internal-kit",
  "version": "1.8.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com",
    "access": "restricted"
  }
}

Public npm token और internal registry token को अलग रखें।

GitHub Actions release

changesets/action version PR बनाता है और merge के बाद publish करता है।

name: Release

on:
  push:
    branches:
      - main

concurrency: release-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm test
      - run: npm run build

      - name: Create release PR or publish to npm
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

PR check:

name: Changeset Check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  changeset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx changeset status --since=origin/main

Documentation-only PR को changeset की जरूरत नहीं हो सकती। लेकिन skip rule team policy में होना चाहिए; Claude Code को CI fix करते समय अपने आप broad exception नहीं जोड़ना चाहिए।

CHANGELOG quality

Weak entry:

---
"@myapp/ui": minor
---

Update Button.

Useful entry:

---
"@myapp/ui": minor
---

Add `variant="outline"` to `Button`.

Existing `solid` and `ghost` variants keep the same props and class names. Teams using a custom theme should add `--button-outline-border` only if they want to override the default border color.

Review prompt:

इस changeset को public CHANGELOG note की तरह review करें।

Check:
- क्या user impact समझ सकता है
- क्या text proposed SemVer bump से match करता है
- migration चाहिए तो steps लिखे हैं या नहीं
- "updated" या "improved" जैसे vague words details की जगह तो नहीं हैं
- package, function और prop names repo में सच में exist करते हैं या नहीं

Suspicious points को questions के रूप में list करें। Silent rewrite न करें।

Common failures

पहली गलती: “version बढ़ा दो” कहना। Claude Code सीधे package.json edit कर सकता है और changeset नहीं छोड़ेगा।

दूसरी गलती: breaking change को minor publish करना। TypeScript type change भी users का build तोड़ सकता है।

तीसरी गलती: internal package publish होना। private: true, ignore, publishConfig.registry, token permissions और npm pack --dry-run साथ में check करें।

चौथी गलती: internal dependency bump भूलना। अगर @myapp/core बदलता है, तो @myapp/cli को भी release चाहिए हो सकता है।

Local verification

Release से पहले:

npm run changeset:status
npm test
npm run build
npm run version -- --snapshot canary
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock CHANGELOG.md
npm pack --dry-run

Snapshot publish किए बिना version calculation और CHANGELOG check करता है। npm pack --dry-run tarball content दिखाता है, जिससे .env, बड़े fixtures, internal docs या missing build artifacts मिलते हैं।

Monetization और team rollout

Reliable release flow revenue से जुड़ता है। UI kit, CLI, SDK या template package paid products, training और consulting का आधार बन सकते हैं। गलत version bump और vague CHANGELOG trust घटाते हैं।

Real repository में लागू करने के लिए Claude Code training और consultation में Changesets, CLAUDE.md, GitHub Actions, npm token boundaries, review prompts और monorepo package policy साथ में design किए जा सकते हैं।

Hands-on result

मैंने इस flow को छोटे npm workspace पर verify किया: Changesets init, changeset creation, changeset status, release PR design और publish guardrails। Claude Code diff से release note draft करने में अच्छा है, लेकिन SemVer अकेले तय करने में unreliable हो सकता है। उससे पूछें “यह breaking change क्यों नहीं है?”; इससे गलत minor या patch bumps जल्दी पकड़े जाते हैं।