withastro/astro

Changeset

Crie arquivos de changeset para o monorepo Astro. Changesets declaram quais pacotes mudaram, o tipo de bump semver e uma mensagem voltada para o usuário que se torna a entrada do CHANGELOG.

Todo PR que modifica um pacote precisa de um changeset. Apenas mudanças em examples/* são isentas.

Criando o Arquivo

Execute pnpm changeset --empty a partir da raiz do repositório. Isso cria um arquivo .md com nome aleatório em .changeset/ com front matter vazio — não é necessário inventar um nome de arquivo nem inspecionar o diretório. Em seguida, edite o arquivo gerado para adicionar o bump do pacote e a mensagem.

Formato

---
'<nome-do-pacote>': patch
---

<mensagem do changeset>

• Os nomes dos pacotes devem corresponder exatamente ao campo name no package.json do pacote (por exemplo, 'astro', '@astrojs/node')
• Tipos de bump: patch, minor ou major
• Um único arquivo de changeset pode cobrir vários pacotes
• Bumps major e minor no pacote principal astro são bloqueados pelo CI e exigem revisão de mantenedor

Escrevendo a Mensagem

A mensagem do changeset é uma entrada pública do CHANGELOG. Escreva-a para usuários do Astro, não para revisores de código.

Comece com um verbo no presente que complete a frase "Este PR...":

• Adiciona, Remove, Corrige, Atualiza, Refatora, Melhora, Deprecia

Descreva a mudança como alguém que constrói um site Astro a experimentará, não como foi implementada internamente:

// Muito focado na implementação
Registra erros úteis se o conteúdo for inválido

// Melhor — impacto para o usuário
Adiciona registro de erros de configuração de coleções de conteúdo.

Atualizações patch

Uma linha geralmente é suficiente. Nenhuma pontuação final é necessária, a menos que esteja escrevendo várias frases.

---
'astro': patch
---

Corrige um bug onde a auditoria da barra de ferramentas sinalizava incorretamente imagens como acima da dobra

---
'astro': patch
---

Refatora o tratamento interno de estilos e scripts para coleções de conteúdo para melhorar o desempenho da build

Ajude o leitor a descobrir se a mudança é relevante para ele. Inclua o nome específico da API (com formatação de crase) quando a mudança estiver ligada a uma opção ou função reconhecível. Quando a API não for voltada para o usuário, descreva o caso de uso ou o resultado final:

// Vago
Melhora a geração automática de fallbacks

// Claro — o leitor pode saber se isso o afeta
Melhora a geração automática de `fallbacks` para a API experimental de Fontes

Novas funcionalidades (minor)

Comece com "Adiciona", nomeie a nova API e descreva o que os usuários agora podem fazer. Inclua um exemplo de código quando útil:

---
'astro': minor
---

Adiciona uma nova propriedade opcional `timeout` para a diretiva `client:idle`

Este valor permite que você especifique um tempo máximo de espera, em milissegundos, antes de hidratar um componente de framework de UI.

```astro
<Button client:idle={{ timeout: 500 }} />
```

Novas funcionalidades são uma oportunidade para escrever uma descrição mais rica que pode alimentar posts de blog. Veja a documentação de changeset do Astro para orientação sobre entradas mais longas.

Breaking changes (major)

Use verbos como "Remove", "Altera" ou "Deprecia". Deve incluir orientação de migração. Use exemplos de código diff quando apropriado:

---
'astro': major
---

Remove o suporte para a propriedade `path` de linguagem personalizada do Shiki. O arquivo JSON da linguagem agora deve ser importado e passado para a opção.

```diff
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
-       { path: './custom.tmLanguage.json' },
+       customLang,
      ],
    },
  },
})
```

Mudanças nos valores padrão devem mencionar o padrão antigo, o novo padrão e como restaurar o comportamento anterior.

Changesets mais longos

Para descrições mais longas, use cabeçalhos #### e mais profundos (nunca ## ou ###) para dividir seções. Isso mantém o CHANGELOG legível quando sua entrada é incorporada:

---
'astro': minor
---

Adiciona uma nova API de Sessões para armazenar estado do usuário entre requisições para páginas renderizadas sob demanda.

#### Configurando o armazenamento de sessão

<!-- ... -->

#### Usando sessões

<!-- ... -->