Implementando Gerenciamento de Versão com Changeset usando Claude Code

Alcançando Gerenciamento de Versão Sistemático com Changeset

O Changeset é uma ferramenta que automatiza o gerenciamento de versão de pacotes e a geração de CHANGELOG. É especialmente poderoso em ambientes monorepo, permitindo construir fluxos de release consistentes que consideram as dependências entre pacotes. O Claude Code oferece suporte preciso desde a configuração até a integração com CI.

Configuração Inicial

Vamos pedir ao Claude Code para fazer a configuração.

> Introduza o Changeset no projeto monorepo.
> Inclua release automático com GitHub Actions e geração de CHANGELOG.

# Instalação
npm install -D @changesets/cli @changesets/changelog-github

# Inicialização
npx changeset init

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

Criação de Changesets

Veja como criar arquivos Changeset que descrevem o conteúdo das alterações.

# Criar Changeset interativamente
npx changeset

<!-- .changeset/happy-dogs-fly.md -->
---
"@myapp/ui": minor
"@myapp/utils": patch
---

Adicionada a variante "outline" ao componente de botão.
Melhorada a definição de tipos das funções utilitárias.

Exemplo de prompt para pedir ao Claude Code a criação de um Changeset.

> Crie um Changeset para as alterações atuais.
> Mudança de versão minor para @myapp/ui, inclua a descrição.

Configuração de npm scripts

// package.json
{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status",
    "version": "changeset version",
    "release": "changeset publish",
    "prerelease": "npm run build"
  }
}

Release Automático com GitHub Actions

Workflow que cria automaticamente um PR de atualização de versão ao fazer merge de PRs, e publica no npm após o merge.

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

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

permissions:
  contents: write
  pull-requests: write
  packages: write

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm run build

      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: atualização de versão"
          commit: "chore: atualização de versão"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Configuração Avançada para Monorepo

Padrões de configuração para gerenciar a coordenação entre pacotes.

// .changeset/config.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"
}

• fixed - Grupo de pacotes que sempre terão a mesma versão
• linked - Grupo de pacotes cujas versões são incrementadas em conjunto

Gerenciamento de Pre-releases

Fluxo de release para versões beta e RC.

# Entrar no modo pre-release
npx changeset pre enter beta

# Adicionar Changeset
npx changeset

# Aplicar versão pre-release
npx changeset version
# => 1.0.0 -> 1.1.0-beta.0

# Publicar
npx changeset publish

# Sair do modo pre-release
npx changeset pre exit

Validação de Changesets

Workflow para verificar no CI se o PR contém um Changeset.

# .github/workflows/changeset-check.yml
name: Changeset Check

on:
  pull_request:
    branches: [main]

jobs:
  changeset-check:
    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
      - name: Check for changeset
        run: npx changeset status --since=origin/main

Formato Personalizado de CHANGELOG

Padrão para personalizar a saída do CHANGELOG.

// .changeset/changelog-config.ts
import type { ChangelogFunctions } from "@changesets/types";

const changelogFunctions: ChangelogFunctions = {
  getDependencyReleaseLine: async () => "",
  getReleaseLine: async (changeset, type) => {
    const [firstLine, ...rest] = changeset.summary
      .split("\n")
      .map((l) => l.trimEnd());

    const date = new Date().toISOString().slice(0, 10);

    let returnVal = `- ${firstLine}`;

    if (rest.length > 0) {
      returnVal += `\n${rest.map((l) => `  ${l}`).join("\n")}`;
    }

    return returnVal;
  },
};

export default changelogFunctions;

Resumo

O Changeset é uma ferramenta poderosa para automatizar o gerenciamento de versão sistemático e o fluxo de release. Com o Claude Code, é possível construir eficientemente desde a configuração inicial até a integração com CI e suporte a monorepo.

Para métodos de gerenciamento de monorepo, consulte o Guia de Gerenciamento de Monorepo, e para o design de pipelines CI/CD, consulte o Guia de Configuração CI/CD. Consulte também a documentação oficial do Changesets.