Como automatizar o processo de versionamento de um projeto em Javascript

Introduo

Como desenvolvedores, amamos automatizar tarefas rotineiras. Nesta publicao demonstrarei a automao do fluxo de release utilizando a biblioteca semantic-release. Esta library permite automatizar todo o processo de gerao de release; Determinando o nmero da prxima verso, criando a nova tag, gerando as novas release notes e a publicao do pacote no NPM, caso seja necessrio.

Para tudo isso funcionar, a biblioteca faz uso das mensagens de commits para determinar o nmero da prxima verso, o Changelog e a publicao. Por padro o semantic-release utiliza a especificao de mensagens de commits do Angular o Conventional Commits e a conveno semver para o nmero de verso.

Resumindo o SemVer nos diz como devem ser os nmeros de nossas verses, como por exemplo: MAJOR.MINOR.PATCH. J o Conventional Commits nos diz como devem ser nossos commits, para que o de/para do commit pro SemVer seja feito de forma automtica.

Abaixo mostrarei uma imagem desse de/para:

No CI o semantic-release deve ser executado aps o build ser feito com sucesso no branch de release, por exemplo.

Como funciona

O semantic-release verifica os commits de um branch entre a ltima tag gerada at o ltimo commit deste branch, para ento acionar a gerao de uma nova tag. Em seguida ele cria ou atualiza o arquivo de Changelog com base nos commits entre as duas tags.

N prtica fica da seguinte forma, como mostrado na imagem a seguir:

Observe que no final imagem temos uma tag 1.17.1 e aps realizarmos um commit novo no branch de release, o semantic-release acionado e cria uma nova tag com a numerao 1.17.2. Em seguida, realizamos dois commits um de docs e outro de fix, quando esses commits vo para o branch de release acionado novamente e temos uma nova tag 1.17.3. Depois disso, temos mais um commit de feat no branch de release e nossa nova tag 1.18.0.

E nosso arquivo de Changelog fica da seguinte maneira:

importante notar que cada tag foi associada a uma release, a tag 1.17.1 tem uma release associada e nas notas de release temos os commits que foram feitos naquela tag.

Por ltimo, mas no menos importante possvel executar o semantic-release sem acionar a gerao de uma nova release, basta executar ele como dry-run. Isso uma salvao quando estamos no processo de configurao ou queremos ver o Changelog daquela verso.

Configurao

Nessa seo descreverei passo a passo de como configurar o semantic-release em um projeto. Uma observao possvel que as verses dos pacotes estejam diferentes, ou seja, mais atualizados aps a publicao desse blog post.

• Criar um repositrio git e adiciona-lo ao remoto no Github ou usar um repositrio j existente;

git init

• Realizar as configuraes necessrias do semantic-release. Note que, se for um projeto novo necessita de yarn init;

yarn init

• Agora precisamos adicionar o pacote do semantic-release nas dev dependencies;

yarn add semantic-release -D

• Em seguida precisamos adicionar os plugins do semantic-release;

yarn add @commitlint/cli @commitlint/config-conventional @semantic-release/changelog @semantic-release/git -D

• Cada plugin tem um propsito especifico:

  • @commitlint/cli: um analisador de mensagem de commit para verificar se a mensagem do commit est segundo o padro;
  • @commitlint/config-conventional: o configurador de um padro a ser seguido nas mensagens de commit, como por exemplo o padro do Angular;
  • @semantic-release/changelog: Plugin que atualiza ou cria o arquivo de Changelog;
  • @semantic-release/git: Plugin que realiza os commits de release e artefatos gerados;

• Adicionar o pacote Husky (opcional):

  • Esse passo interessante pois com o husky evitamos de subir commits fora do padro;

• Criar um arquivo .releaserc.json exemplo disponvel na doc:

  • O arquivo .releaserc.json ficou da seguinte maneira;

{  "plugins": [    "@semantic-release/commit-analyzer",    "@semantic-release/release-notes-generator",    "@semantic-release/github",    "@semantic-release/changelog",    [      "@semantic-release/npm",      {        "npmPublish": false      }    ],    {      "path": "@semantic-release/git",      "assets": ["package.json", "package-lock.json", "CHANGELOG.md"],      "message": "chore(release): ${nextRelease.version} [skip ci]

${nextRelease.notes}"    }  ],  "branches": [    "main"  ]}

• Criar uma workflow para ser executado no Github action:
  • Criar um .env com a seguinte key GITHUB_TOKEN e o seu access token do Github;
  • Criar um diretrio Github workflows com um arquivo dentro: .github/workflows/release.yml;
  • Temos o arquivo .github/workflows/release.yml dessa forma;

name: Releaseon:  push:    branches:      - mainjobs:  release:    name: Release    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v3        with:          fetch-depth: 0      - name: Setup Node.js        uses: actions/setup-node@v3        with:          node-version: 'lts/*'      - name: Install dependencies        run: yarn install      - name: Release        env:          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}        run: yarn release

• Adicionar o comando do semantic-release nos scripts do package.json:
  • Por ltimo o package.json est assim;

{  "name": "poc-release",  "version": "0.1.0",  "main": "index.js",  "repository": {    "type": "git",    "url": "[email protected]:andraderaul/poc-release.git"  },  "author": "Raul Andrade",  "license": "MIT",  "scripts": {    "test": "jest",    "release": "semantic-release",    "release:dry": "semantic-release --dry-run",  },  "devDependencies": {    "@commitlint/cli": "^16.2.3",    "@commitlint/config-conventional": "^16.2.1",    "@semantic-release/changelog": "^6.0.1",    "@semantic-release/git": "^10.0.1",    "husky": "^7.0.4",    "jest": "^27.5.1",    "semantic-release": "^19.0.2"  }}

Repositrios

Para ver o cdigo de configurao na ntegra, acesse o repositrio no github.
As imagens utilizadas nos exemplos so de outro repositrio.

Referncias

semantic-release
Semantic Versioning 2.0.0
Conventional Commits