AutoRelease 0.6.0

Auto Release

Gere automaticamente releases do seu projeto no GitHub usando o Auto Release.

Começando

Use o sumário abaixo para escolher como quer aprender a usar o Auto Release.

• GitHub Actions - Automatize a criação dos seus releases com o CI/CD do GitHub.
• CLI (Interface de Linha de Comando) - Crie os seus releases a partir do seu terminal.

Depois, veja como escrever as suas mensagens de commit para usar todo o potencial do Auto Release clicando aqui.

Índice

• Auto Release
  • Começando
  • Índice
  • GitHub Actions
    • Criando um fluxo de trabalho simples no GitHub Actions
    • Personalizando o fluxo de trabalho
  • CLI (Interface de Linha de Comando)
    • Instalação
  • Escrevendo commits
  • Configurações
    • Arquivo de configuração
    • Variáveis de ambiente
    • Propriedades de configuração
      • CreateComand
      • CreateComand e NoteCommand
      • CreateComand e VersionCommand
  • Autores
  • Licença

GitHub Actions

Para começar a usar o Auto Release no GitHub Actions é muito fácil, siga os passos abaixo e diga adeus a escrever releases manualmente.

Criando um fluxo de trabalho simples no GitHub Actions

Acesse o seu repositório no GitHub e no menu suspenso "Add file", vá em "Create new file".

Em "Name your file..." digite o seguinte: .github/workflows/main.yml.

Ficará semelhante a imagem abaixo:

Copie o código abaixo e cole no corpo do arquivo no GitHub.

# .github/workflows/main.yml

name: Criar Release

on:
  push:
    branches:
      - main

jobs:
  create-release:
    name: Criar Release
    runs-on: ubuntu-latest
    permissions: write-all

    steps:
      - name: Criar Release
        uses: kempdec/autorelease-action@v1
        env:
          AutoRelease_Token: ${{ secrets.GITHUB_TOKEN }} # Este token é fornecido pelo GitHub Actions, você não precisa criar seu próprio token.

Clique no botão "Commit changes".

Escreva a sua mensagem de commit e clique mais uma vez em "Commit changes".

Pronto! Isso já é o suficiente para que o Auto Release comece a gerar automaticamente os releases do seu repositório no GitHub. Toda vez que um push for feito para o branch main, um release será criado.

Veja como configurar e costumizar o Auto Release para que atenda melhor as suas necessidades e da sua equipe clicando aqui.

Personalizando o fluxo de trabalho

Caso você queira disparar a ação de criação da release manualmente, troque o conteúdo de on: push para on: workflow_dispatch.

# .github/workflows/main.yml

name: Criar Release

on:
  workflow_dispatch:

jobs:
  create-release:
    name: Criar Release
    runs-on: ubuntu-latest
    permissions: write-all

    steps:
      - name: Criar Release
        uses: kempdec/autorelease-action@v1
        env:
          AutoRelease_Token: ${{ secrets.GITHUB_TOKEN }} # Este token é fornecido pelo GitHub Actions, você não precisa criar seu próprio token.

Ou se preferir, o release pode ser criado quando você fizer o push de uma tag de versão para o repositório. Nesse caso troque o conteúdo de on: push: branches para on: push: tags e adicione a variável de ambiente AutoRelease_Version.

# .github/workflows/main.yml

name: Criar Release

on:
  push:
    tags:
      - "v*" # Tags que iniciarem com v, como v1.0.0, v2.3.5-beta.1.

jobs:
  create-release:
    name: Criar Release
    runs-on: ubuntu-latest
    permissions: write-all

    steps:
      - name: Criar Release
        uses: kempdec/autorelease-action@v1
        env:
          AutoRelease_Token: ${{ secrets.GITHUB_TOKEN }} # Este token é fornecido pelo GitHub Actions, você não precisa criar seu próprio token.
          AutoRelease_Version: ${{ github.ref_name }}

CLI (Interface de Linha de Comando)

Instalação

Instale a ferramenta a partir do SDK do .NET.

dotnet tool install -g autorelease

Digite o comando autorelease --help em seu Terminal para que seja impresso a ajuda.

Para imprimir a ajuda de algum comando, informe ele e em seguida a opção --help.

Exemplo: autorelease create --help.

A CLI também funciona com um arquivo de configuração do Auto Release. Nos exemplos acima, o arquivo deveria estar em C:\Users\ceo, que é o caminho em que o terminal se encontra.

Veja como usar um arquivo de configuração clicando aqui.

Escrevendo commits

O Auto Release usa o padrão do Conventional Commits (com poucas diferenças) para ler os commits e gerar o release automaticamente.

Ou seja, a mensagem do commit deve ser estruturada da seguinte forma:

Obs.: O Auto Release ainda não oferece suporte a escopos opcionais, mas em breve será adicionado o recurso.

<tipo>: <descrição>

[corpo opcional]

[rodapé(s) opcional(is)]

Os tipos feat e fix, operador !, e o texto BREAKING CHANGE: funcionam como está descrito em Conventional Commits, com as seguintes diferenças:

• Caso a propriedade Types (arquivo) ou types (CLI) seja especificada, o primeiro tipo terá o funcionamento de feat, de incrementar a versão minor e todos os demais tipos incrementarão a versão patch.

• O texto BREAKING CHANGE: pode ser colocado em qualquer lugar do corpo ou rodapé, não sendo necessário estar no início do texto. Apenas se atente ao uso de : (2 pontos), o BREAKING CHANGE: sem os 2 pontos, não será considerado.

• Caso o corpo ou rodapé da mensagem de commit for especificado, somente eles serão utilizados nas notas geradas pelo Auto Release.

  Exemplo da mensagem de commit:

  fix: Corrigir a criação de artigos.
  
  Corrigido um problema em que quando a data de publicação era inferior a data de criação, o artigo não era criado.
  
  Obs.: Somente de exemplo.
  

  As notas geradas serão semelhantes a abaixo:

  # My Project v1.0.0 (2024-01-01)
  
  # Correções
  
  - Corrigido um problema em que quando a data de publicação era inferior a data de criação, o artigo não era criado.
  
    Obs.: Somente de exemplo.
  

Configurações

Arquivo de configuração

Uma das maneiras de configurar o Auto Release, é adicionando um arquivo com o nome autorelease.config.json na raiz do seu projeto.

Exemplo: Se o seu projeto está em D:/MeuProjeto, é nela que o arquivo deverá ser criado.

Um modelo atualizado com todas as opções do autorelease.config.json pode ser encontrado clicando aqui.

Observações:

• Todas as propriedades de configuração são OPCIONAIS.
• A configuração abaixo é apenas um exemplo e NÃO deve ser usada em seu projeto, a menos que entenda o que está fazendo.
• Caso você esteja utilizando o Auto Release no GitHub Actions, as propriedades NoteCommand e VersionCommand devem ser ignoradas.

// autorelease.config.json

{
  // O token para acesso ao repositório no GitHub.
  "Token": "ghp_1DF8350tVc1Ry0IBuWH3uh8cTRpofs0FY0Iv",
  // O repositório que contém os commits no GitHub.
  "Repo": "kempdec/MyRepository",
  // O branch do repositório no GitHub.
  "Branch": "main",

  // As configurações do subcomando de criação automática de um release.
  "CreateCommand": {
    // A versão do release.
    // No exemplo abaixo, o release seria criado na v1.3.0. O uso dela é recomendado somente de forma dinâmica, como em
    // uma variável de ambiente definida pelo GitHub Actions.
    "Version": "v1.3.0",
    // O nome do projeto.
    // Ele pode ser utilizado em alguns lugares, como parte do título do release.
    "ProjectName": "Meu Repositório",
    // Um sinalizador indicando se o release é um rascunho.
    "Draft": false,
    // Um sinalizador indicando se o release é um pre-release.
    "PreRelease": false,
    // O tipo de saída da criação automática do release.
    // Algumas opções são: Id, UploadUrl e Version.
    "OutputType": "Id",

    // Os tipos das mensagens de commit.
    "Types": [
      "feat=Novidades desta versão",
      "fix=Principais correções desta versão",
      "chore=Notas técnicas"
    ],
    // As substituições do início das mensagens de commit.
    "Replaces": {
      "Adicionar": "Foi adicionado",
      "Adicionar o ": "Foi adicionado o ",
      "Adicionar a ": "Foi adicionada a ",
      "Corrigir": "Corrigido um problema em que"
    },
    // Os inícios das mensagens de commit que serão ignoradas.
    "Ignores": [
      "Refatorar."
    ],

    // A primeira versão do repositório.
    "FirstVersion": "0.1.0",
    // O prefixo das versões do repositório.
    "VersionPrefix": "v"
  },

  // As configurações do subcomando de geração automática das notas do release.
  "NoteCommand": {
    // Os tipos das mensagens de commit.
    "Types": [
      "feat=Novidades desta versão",
      "fix=Principais correções desta versão"
    ],
    // As substituições do início das mensagens de commit.
    "Replaces": null,
    // Os inícios das mensagens de commit que serão ignoradas.
    "Ignores": [
      "Refatorar."
    ]
  },

  // As configurações do subcomando de geração automática da versão do release.
  "VersionCommand": {
    // A primeira versão do repositório.
    "FirstVersion": "0.1.0",
    // O prefixo das versões do repositório.
    "VersionPrefix": null
  }
}

Variáveis de ambiente

Você pode definir variáveis de ambiente com o prefixo AutoRelease_ para configurar o Auto Release.

Para configurar o repositório, por exemplo, o nome da variável de ambiente seria AutoRelease_Repo.

// Essa variável de ambiente:
AutoRelease_Repo="kempdec/MyRepository"

// É equivalente a essa propriedade no arquivo de configuração:
{
  "Repo": "kempdec/MyRepository"
}

Use __ (dois _) no nome da variável de ambiente para definir uma propriedade de um objeto.

// Essa variável de ambiente:
AutoRelease_CreateCommand__Types="feat=\"Novidades\" fix=\"Correções\" chore=\"Notas técnicas\""

// É equivalente a essa propriedade no arquivo de configuração:
{
  "CreateCommand": {
    "Types": [
        "types=Novidades",
        "fix=Correções",
        "chore=Notas técnicas"
    ]
  }
}

Propriedades de configuração

CreateComand

CreateComand e NoteCommand

CreateComand e VersionCommand

Autores

• KempDec - Mantedora do projeto de código aberto.
• Vinícius Lima - Desenvolvedor .NET C#.

Licença

MIT