Versioning Workflow

See in English

Versioning Workflow é uma ferramenta que permite a geração automática de versões do seu código. Ele se baseia em conventional commits e padrões de branches para determinar as versões. As versões geradas seguem o versionamento semântico.

Índice

1. Instalação
2. Uso
3. Contato
4. License

1. Instalação

Copie os arquivos create-pre-release.yml e create-release.yml do diretório .github/workflows para um diretório de mesmo nome na raiz do seu projeto. Isso é tudo!

2. Uso

Há dois workflows disponíveis para você usar: o de criação de release e o de criação de pré-release. Você pode optar por usar apenas o workflow de criação de release ou combiná-lo com o workflow de criação de pré-release.

2.1. Workflow de criação de release

name: Release

on:
  push:
    branches: ["main"]

jobs:
  create_release:
    name: Create release
    uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-release-template.yml@v1
    permissions:
      contents: write

Essa é a forma mais básica de uso desse workflow. Ele será disparado sempre que mudanças forem percebidas diretamente na branch principal, por meio de pull requests ou commits diretos. As novas versões são geradas a partir da mensagem dos commits na seguinte ordem de precedência:

Commits que iniciam com BREAKING CHANGE: ou <algum_prefixo>!: (note o uso de !) geram novas versões major do código (por exemplo, de 0.1.0 para 1.0.0).
Commits que iniciam com FIRST RELEASE: em versões não públicas do código (versão 0) geram a versão inicial de lançamento do software (versão 1.0.0).
Commits que iniciam com fix: geram novas versões patch do código (por exemplo, de 0.1.0 para 0.1.1).
Commits em qualquer outro padrão geram versões minor do cóldigo (por exemplo, de 0.1.0 para 0.2.0).

2.1.1. Usando um nome diferente para a branch principal

Por padrão, main é considerada como a branch principal, mas, você pode modificar isso por meio do parâmetro main_branch:

create_release:
  name: Create release
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-release-template.yml@v1
  permissions:
    contents: write
  with:
    main_branch: "master"

2.1.2. O job `upsert_major_version`

No template do arquivo create-release.yml, você notará que há um job chamado upsert_major_version:

upsert_major_version: # Optional
  name: Upsert major version
  needs: create_release
  permissions:
    contents: write
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/upsert-major-version-template.yml@v1
  with:
    version: ${{ needs.create_release.outputs.version }}

Esse job é opcional e pode ser removido se você quiser. A cada versão de lançamento, ele gera uma tag v[major_version] (por exemplo, v1) e a mantém atualizada, sempre referenciando a última versão, até que uma nova versão major seja lançada.

2.2. Workflow de criação de pré-release

create_release_candidate:
  name: Create release candidate
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-pre-release-template.yml@v1
  permissions:
    contents: write

Essa é a forma mais básica de uso do workflow de pré-release. Ele será disparado em eventos de pull request: na abertura, durante novos commits e na sua reabertura. Cada nova mudança em uma pull request gerará uma versão release candidate (-rc-<number>).

As versões de release candidate são incrementadas a cada nova alteração (por exemplo, de 0.1.0-rc-1 para 0.1.0-rc-2). Novas versões de release candidate (-rc-1) são geradas levando em consideração o nome das branches de origem e o padrão dos commits, na seguinte ordem de precedência:

Commits que começam com BREAKING CHANGE: ou <algum_prefixo>!: gerarão versões major.
Commits que iniciam com FIRST RELEASE: em versões não públicas do código (versão 0) gerarão a versão inicial de lançamento do software (versão 1.0.0).
Branches que correspondem ao parâmetro feature_branches gerarão versões minor do código.
Branches que correspondem ao parâmetro release_branches também gerarão versões minor do código.
Branches que correspondem ao parâmetro hotfix_branches gerarão versões patch do código.

Se a branch não corresponder a nenhum dos padrões anteriores, a versão automática de pré-release não será gerada.

2.2.1. Customizando nomes de branches para gerar as versões

Assim como no workflow de criação de release, você também pode informar um nome diferente para a branch principal por meio de main_branch. O mesmo vale para branches de feature, release e hotfix:

Para gerar versões minor, o workflow procurará por branches que correspondam ao padrão dos parâmetros feature_branches e release_branches. Se algum dos parâmetros não for informado, o valor feature será considerado como nome padrão para feature_branches e release para release_branches.
Para gerar versões pacth, o workflow procurará por branches que correspondam ao padrão do parâmetro hotfix_branches. Se o parâmetro não for informado, o valor hotfix será considerado como nome padrão.

create_release_candidate:
  name: Create release candidate
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-pre-release-template.yml@v1
  permissions:
    contents: write
  with:
    main_branch: "main"
    feature_branches: "feature"
    release_branches: "release"
    hotfix_branches: "hotfix"

2.2.2. Usando mais de um nome de branch para gerar as versões

Por fim, você também pode usar mais de um nome de branch para os parâmetros feature_branches, release_branches e hotfix_branches, caso queira. Por exemplo:

create_release_candidate:
  name: Create release candidate
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-pre-release-template.yml@v1
  with:
    feature_branches: "feat feature" # aceitará correspondência da branch de origem tanto para 'feat' quanto para 'feature'
    release_branches: "rel release" # aceitará correspondência da branch de origem tanto para 'rel' quanto para 'release'
    hotfix_branches: "fix hotfix" # aceitará correspondência da branch de origem tanto para 'fix' quanto para 'hotfix'

2.3. Usando o prefixo `v` para as versões

Algumas ferramentas, como o Github, sugerem o uso de versões que comecem com v como, por exemplo, v1.0.0. Você pode habilitar esse comportamento através da flag use_v_prefix:

Workflow de criação de release

create_release:
  name: Create release
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-release-template.yml@v1
  permissions:
    contents: write
  with:
    use_v_prefix: true

Workflow de criação de pre release

create_release_candidate:
  name: Create release candidate
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-pre-release-template.yml@v1
  permissions:
    contents: write
  with:
    use_v_prefix: true

2.4. Customizando o nome da release

Por padrão, os nomes das releases geradas recebem o nome usado para gerar a versão. Você pode sobrescrever esse comportamento através da propriedade release_name:

Workflow de criação de release

create_release:
  name: Create release
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-release-template.yml@v1
  permissions:
    contents: write
  with:
    release_name: "My Amazing Release"

Workflow de criação de pre release

create_release_candidate:
  name: Create release candidate
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-pre-release-template.yml@v1
  permissions:
    contents: write
  with:
    release_name: "My Amazing Release"

Com essa propriedade, todas as releases criadas receberão o nome "My Amazing Release" ao invés do nome da versão.

2.5. Adicionando um prefixo ao nome da release

Você também pode definir um prefixo a ser adotado no nome da release. Isso é útil em casos que você ainda deseja manter a versão gerada no nome da release, mas quiser adicionar um prefixo de nome de sua escolha. Isso pode ser obtido por meio da propriedade release_name_prefix:

Workflow de criação de release

create_release:
  name: Create release
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-release-template.yml@v1
  permissions:
    contents: write
  with:
    release_name_prefix: "Github"

Workflow de criação de pre release

create_release_candidate:
  name: Create release candidate
  uses: davidsonbrsilva/versioning-workflow/.github/workflows/create-pre-release-template.yml@v1
  permissions:
    contents: write
  with:
    release_name_prefix: "Github"

Neste exemplo, as releases criadas seguirão o padrão "Github ..", como em "Github 1.0.0".

3. Contato

Para dúvidas ou sugestões, envie e-mail para davidsonbruno@outlook.com.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.pt.md

README.pt.md

Versioning Workflow

Índice

1. Instalação

2. Uso

2.1. Workflow de criação de release

2.1.1. Usando um nome diferente para a branch principal

2.1.2. O job `upsert_major_version`

2.2. Workflow de criação de pré-release

2.2.1. Customizando nomes de branches para gerar as versões

2.2.2. Usando mais de um nome de branch para gerar as versões

2.3. Usando o prefixo `v` para as versões

2.4. Customizando o nome da release

2.5. Adicionando um prefixo ao nome da release

3. Contato

4. License

Files

README.pt.md

Latest commit

History

README.pt.md

File metadata and controls

Versioning Workflow

Índice

1. Instalação

2. Uso

2.1. Workflow de criação de release

2.1.1. Usando um nome diferente para a branch principal

2.1.2. O job upsert_major_version

2.2. Workflow de criação de pré-release

2.2.1. Customizando nomes de branches para gerar as versões

2.2.2. Usando mais de um nome de branch para gerar as versões

2.3. Usando o prefixo v para as versões

2.4. Customizando o nome da release

2.5. Adicionando um prefixo ao nome da release

3. Contato

4. License

2.1.2. O job `upsert_major_version`

2.3. Usando o prefixo `v` para as versões