Versioning Changesets yang Aman dengan Claude Code

Claude Code bisa mempercepat pekerjaan release, tetapi nomor versi tidak boleh diputuskan asal-asalan. Breaking change yang terbit sebagai patch dapat merusak build pengguna. Package internal yang tidak sengaja dipublish ke npm juga sulit dibersihkan. Changesets membantu karena setiap PR harus mencatat package mana yang berubah, bump apa yang diperlukan, dan alasannya.

Panduan ini membahas workflow praktis Claude Code dengan Changesets: dasar SemVer, release notes, package monorepo, package private/internal, GitHub Actions, risiko npm publish, kualitas CHANGELOG, dan prompt review agar AI tidak membuat version bump yang salah. Rujukan resmi yang sebaiknya dibuka adalah SemVer, Changesets, dokumentasi npm publishing, dan GitHub Actions. Untuk konteks ClaudeCodeLab, baca juga praktik CLAUDE.md, setup CI/CD, dan manajemen monorepo.

Tetapkan SemVer lebih dulu

SemVer berarti semantic versioning. Format 1.4.2 adalah major.minor.patch. patch untuk bug fix tanpa mengubah kontrak publik. minor untuk fitur baru yang tetap backward-compatible. major untuk perubahan yang mungkin memaksa pengguna mengubah kode.

Kontrak publik bukan hanya nama fungsi. Props React, token CSS, flag CLI, exit code, perilaku default, dan tipe TypeScript yang diekspor juga termasuk. Aturan ini perlu masuk ke prompt Claude Code, karena model bisa salah menilai bump jika hanya melihat ukuran diff.

Use case yang sering terjadi:

Use case	Risiko	Yang direview Claude Code
UI package	props, variant, CSS token, peer dependency	apakah bump cocok dengan perubahan API publik
CLI package	flag, command, exit code	apakah README, test, dan code masih selaras
Monorepo	range dependensi internal	apakah package dependen juga perlu release
Package internal	salah publish ke npm	private, ignore, registry, token

Setup awal

Install dan inisialisasi Changesets.

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

Gunakan .changeset/config.json seperti ini sebagai awal:

{
  "$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 menjaga sekelompok package selalu di versi yang sama. linked menaikkan package terkait bersama-sama, tetapi tetap mempertahankan nomor versi masing-masing. updateInternalDependencies mengatur update range dependensi workspace. Di monorepo, build lokal bisa lolos dengan workspace:*, tetapi package yang sudah dipublish bisa gagal di pengguna jika range salah.

Tambahkan scripts yang konsisten:

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

Menulis changeset

Untuk setiap PR yang memengaruhi kontrak package publik:

npx changeset

Contoh:

---
"@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 mendapat minor karena menambah opsi yang kompatibel. @myapp/utils mendapat patch karena memperbaiki fungsi yang sudah ada. Jika prop dihapus, flag CLI diganti nama, atau perilaku default berubah, perlakukan sebagai kandidat major.

Prompt untuk Claude Code:

Baca diff PR saat ini dan buat draft Changesets changeset.

Aturan:
- Ikuti SemVer: breaking change = major, fitur kompatibel = minor, fix = patch
- Jangan edit version di package.json secara langsung
- Jangan jalankan npm publish
- Jangan masukkan package private: true ke rencana publish

Kembalikan:
- daftar package yang berubah
- bump rekomendasi untuk tiap package
- alasan
- draft isi .changeset/*.md
- poin yang masih perlu review manusia

Monorepo dan package internal

Repository nyata sering mencampur package yang dipublish dan app yang hanya dideploy. Misalnya @myapp/ui dipublish ke npm, sedangkan @myapp/app hanya web app.

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

Di Changesets, package yang tidak ingin dirilis bisa diabaikan:

{
  "$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"]
}

Untuk registry internal, tulis registry secara eksplisit dan pisahkan token dari token npm publik.

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

Release dengan GitHub Actions

changesets/action dapat membuat version PR dan publish setelah PR itu dimerge.

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 }}

Tambahkan check di PR:

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

PR dokumentasi mungkin tidak butuh changeset. Namun rule untuk skip harus menjadi aturan tim, bukan pengecualian yang dibuat Claude Code hanya agar CI lolos.

Kualitas CHANGELOG

Contoh buruk:

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

Update Button.

Contoh lebih berguna:

---
"@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.

Prompt review:

Review changeset ini sebagai teks CHANGELOG publik.

Cek:
- apakah pengguna memahami dampaknya
- apakah teks cocok dengan bump major/minor/patch
- apakah langkah migration ditulis jika diperlukan
- apakah kata vague seperti "updated" atau "improved" menggantikan detail
- apakah nama package, fungsi, dan props benar-benar ada

Tuliskan poin mencurigakan sebagai pertanyaan. Jangan rewrite diam-diam.

Kegagalan umum

Pertama, meminta “naikkan versi”. Claude Code bisa langsung mengedit package.json tanpa membuat changeset.

Kedua, breaking change dipublish sebagai minor. Perubahan tipe TypeScript pun bisa merusak build pengguna.

Ketiga, package internal ikut dipublish. Periksa private: true, ignore, publishConfig.registry, izin token, dan npm pack --dry-run.

Keempat, lupa dependency bump internal. Jika @myapp/core berubah, @myapp/cli mungkin juga perlu release.

Verifikasi lokal

Sebelum 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 mengecek perhitungan versi dan CHANGELOG tanpa publish. npm pack --dry-run menunjukkan isi tarball, sehingga kamu bisa menemukan .env, fixture besar, dokumen internal, atau build artifact yang hilang.

Monetisasi dan rollout tim

Release flow yang stabil mendukung pendapatan. UI kit, CLI, SDK, atau template package bisa menjadi produk berbayar, training, platform internal, atau konsultasi. Sebaliknya, version bump yang salah dan CHANGELOG yang kosong akan merusak kepercayaan.

Untuk menerapkan ini di repository nyata, training dan konsultasi Claude Code dapat membantu merancang Changesets, CLAUDE.md, GitHub Actions, batas token npm, prompt review, dan policy package monorepo.

Hasil uji langsung

Saya mengecek alur ini dengan npm workspace kecil: inisialisasi Changesets, membuat changeset, menjalankan changeset status, merancang release PR, dan memeriksa guardrail publish. Claude Code kuat untuk membuat draft release note dari diff, tetapi kurang stabil jika diminta menentukan SemVer sendiri. Prompt “jelaskan mengapa ini bukan breaking change” membantu menemukan bump minor atau patch yang meragukan sebelum sampai ke npm.