Como implementar a liberação semântica para pacotes públicos sem escopo

Instruções detalhadas sobre como publicar um pacote público sem escopo usando liberação semântica aproveitando o poder do GitHub Actions

No cenário de desenvolvimento de software em evolução, manter a consistência das versões e automatizar o processo de lançamento é mais importante do que nunca. Digitar Liberação Semântica : uma ferramenta projetada para garantir um versionamento claro e estruturado. Para desenvolvedores que utilizam pacotes públicos sem escopo, o processo pode parecer assustador. No entanto, com o poder das ações do GitHub ao nosso alcance, a automação se torna muito fácil.

Este artigo oferece um guia detalhado e abrangente, fornecendo instruções passo a passo para integrar perfeitamente o Semantic Release ao seu fluxo de trabalho, adaptado especificamente para aqueles que usam pacotes públicos sem escopo. Mergulhe e descubra a abordagem simplificada para lançamentos de software.

Quando eu criei meu pacote público , encontrei obstáculos para publicá-lo perfeitamente no NPM. Foi um desafio garantir as configurações corretas.

Para acertar, vamos passar por uma experiência passo a passo para a publicação adequada de pacotes públicos para NPM .

Visão geral do conteúdo

• Dê um nome ao pacote
• Crie um pacote
• Fonte do pacote
• Fichas
• Configuração de ações do GitHub
• Liberação semântica
• Formato de confirmação
• Pacote publicado
• Conclusão

Dê um nome ao pacote

Antes de começar a implementar nosso pacote, é melhor encontrar o nome adequado para ele. Para ter certeza de que o nome ainda não está em uso - verifique my_package_name e leve-o para o seu pacote. Eu escolhi “tokky”. A partir daí, é impossível reservar o nome do pacote. Para o nome no npm, você deve publicar o pacote.

Crie um pacote

O objetivo é desenvolver um pacote simples que envie conteúdo para o console. Precisamos ter certeza de que podemos instalá-lo e executá-lo. Para o processo de construção, vamos usar simples construir .

Durante este artigo, usarei o nome do pacote tokky . Vamos criar package.json com os dados iniciais.

 mkdir tokky && cd tokky && npm init -y

Após executar o comando, o sistema gerou um arquivo package.json padrão para o projeto, que se parece com este:

 { "name": "tokky", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" }

Neste guia, o arquivo package.json desempenha um papel crucial para garantir a configuração correta. Neste momento, vamos especificar a versão do nó para nosso pacote:

 echo "v18" > .nvmrc

e ative a versão especificada com o seguinte:

 nvm use

Para o arquivo README.md :

 echo "# Tokky\n\nA simple zero dependency logger for node js." > README.md

Por fim, instale as dependências de desenvolvimento:

 npm i -D esbuild eslint prettier

Em nossa configuração inicial, precisamos abordar vários pontos-chave no package.json :

• main : designa o ponto de entrada principal do módulo.
• bin : aqui você especificará quaisquer executáveis fornecidos pelo seu módulo.
• files : deve conter uma matriz de padrões de arquivo que serão incluídos quando o pacote for compactado e posteriormente publicado no registro npm.
• private : certifique-se de que esteja definido como false , pois nosso pacote deve ser público.
• publishConfig : O acesso para isso deve ser definido como public .

Após essas configurações, seu package.json deverá se parecer com o seguinte:

 { "name": "tokky", "version": "1.0.0", "description": "Node js logger package", "main": "dist/index.js", "scripts": { "build": "esbuild src/index.js --bundle --platform=node --format=cjs --minify --outfile=dist/index.js", }, "files": [ "dist" ], "bin": { "tokky": "./dist/index.js" }, "keywords": [ "logger", "nodejs", "tokky" ], "private": false, "author": { "name": "Anton Kalik", "email": "[email protected]", "url": "https://idedy.com" }, "publishConfig": { "access": "public" }, "license": "MIT", "engines": { "node": "18.xx" }, "devDependencies": { "esbuild": "^0.19.2", "eslint": "^8.49.0", "prettier": "^3.0.3" } }

package.json após a configuração inicial

Além disso, vamos adicionar dois arquivos ignorados:

 .idea node_modules dist

.gitignore

e para npm:

 .idea /src/ /node_modules/ /test/ /.nvmrc .github/

.npmignore

Por fim, descreverei minha configuração para ESLint. No entanto, lembre-se de que a configuração pode variar de acordo com os requisitos específicos do seu pacote.

 module.exports = { env: { browser: true, commonjs: true, es2021: true, node: true, }, extends: "eslint:recommended", overrides: [ { env: { node: true, }, files: ["src/**/*.js", ".eslintrc.{js,cjs}"], parserOptions: { sourceType: "script", }, }, ], parserOptions: { ecmaVersion: "latest", }, rules: {}, };

Configuração .eslintrc.js

Em seguida, acesse o GitHub e estabeleça um novo repositório. Nomeie-o com o nome do seu pacote.

Prossiga executando os comandos subsequentes:

 git init git add . git commit -m "first commit" git branch -M main git remote add origin [email protected]:<your_github_username>/tokky.git git push -u origin main

Fonte do pacote

A seguir, vamos criar um aplicativo básico e configurá-lo para construção. Dentro da pasta src , gere um arquivo index.js e preencha-o com o seguinte conteúdo:

 #!/usr/bin/env node const os = require('os'); const username = os.userInfo().username; if (process.argv[2] === 'hi') { console.log(`Hello ${username}`); }

Script simples para exemplo de pacote

O conceito é simples: executar my_package_name hi deve exibir “Hello [nome de usuário]”.

Para validar esta funcionalidade, execute o comando diretamente do seu repositório usando:

 node src/index.js hi

Se o resultado estiver alinhado com as expectativas, é hora de construir a fonte:

 npm run build

A execução bem-sucedida deste comando produzirá uma pasta dist contendo um arquivo index.js reduzido.

Fichas

A execução do lançamento semântico, que determinará alterações de versão e tratará do processo de lançamento com base em mensagens de commit, requer variáveis de ambiente ( GITHUB_TOKEN , NPM_TOKEN ) para operar corretamente. Os tokens são obtidos dos segredos do GitHub, garantindo que permaneçam confidenciais.

Para definir GITHUB_TOKEN , navegue aqui: https://github.com/settings/tokens

Gere o token usando um menu suspenso. Clique no novo token de acesso pessoal (clássico) e defina a permissão como na imagem.

Use o nome do seu pacote conforme mostrado abaixo:

Uma vez gerado, copie o valor do token e mantenha-o confidencial – é crucial não compartilhar isso com outras pessoas. Armazene temporariamente esse token com segurança, pois precisaremos dele em breve para a CLI do Semantic Release.

Para gerar o NPM_TOKEN , primeiro você precisa de uma conta no Site oficial do npm . Se você ainda não se cadastrou, passe pelo processo de cadastro. Depois disso, navegue até:

 https://www.npmjs.com/settings/<your_user_name>/tokens/new

e gerar um token “clássico” com a opção “publicar”.

Copie o valor gerado do token e navegue até os segredos do GitHub:

 https://github.com/<your_user_name>/<your_repo_name>/settings/secrets/actions/new

e coloque o novo segredo como NPM_TOKEN nos segredos do repositório:

Com nossos segredos agora configurados, podemos configurar GitHub Actions.

Configuração de ações do GitHub

Para automatizar nossos processos, usaremos GitHub Actions. Esta é uma ferramenta CI/CD integrada ao GitHub. Ele permite que os desenvolvedores automatizem fluxos de trabalho diretamente de seus repositórios GitHub, como construção, teste e implantação de aplicativos. Ao definir fluxos de trabalho em arquivos YAML, os usuários podem acionar ações com base em eventos específicos, como solicitações push e pull ou horários agendados, tornando o processo de desenvolvimento de software mais eficiente e automatizado.

Para começar, crie um diretório .github na raiz do seu projeto. Dentro deste diretório, estabeleça uma subpasta workflows .

Aqui, crie nosso arquivo de configuração chamado release.yml e preencha-o com o seguinte conteúdo:

 name: Release package on: push: branches: - main jobs: release: runs-on: ubuntu-latest if: ${{ github.ref == 'refs/heads/main' }} steps: - name: Checkout uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: "18" - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Semantic Release run: npm run semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Este fluxo de trabalho aciona um evento push para a ramificação principal. Ele está configurado para executar o trabalho na máquina virtual Ubuntu mais recente que o GitHub oferece. Embora não seja imperativo nos aprofundarmos em todos os trabalhos, vamos destacar alguns específicos. Perto do final, observe como invocamos npm run semantic-release usando os tokens designados.

Liberação semântica

Para o processo de liberação automatizada, usaremos a Liberação Semântica. Esta ferramenta lida com versionamento e publicação de pacotes com base na semântica da mensagem de commit. Ele segue as convenções do Versionamento Semântico (SemVer) para determinar alterações de versão (maior, secundária ou patch). Ao analisar mensagens de commit, elimina as etapas manuais de controle de versão, garante números de versão consistentes e agiliza o processo de lançamento. Vamos configurar isso.

Para essa configuração, usaremos este código GitHub e execute-o em seu repositório:

 npx semantic-release-cli setup

E acompanhe as perguntas:

 % npx semantic-release-cli setup ? What is your npm registry? https://registry.npmjs.org/ ? What is your npm username? your_user_name ? What is your npm password? [hidden] ? What is your NPM two-factor authentication code? 00000000 ? Provide a GitHub Personal Access Token (create a token at https://github.com/s ettings/tokens/new?scopes=repo) ghp_your_token_here ? What CI are you using? Github Actions

Você já deve ter seu Token Pessoal. Basta inseri-lo quando solicitado. Da mesma forma, as ações do GitHub que configuramos utilizarão o NPM_TOKEN que estabelecemos anteriormente nos segredos do repositório. Se você verificar agora seu package.json , a versão será exibida como:

 "version": "0.0.0-development",

e novo roteiro:

 "semantic-release": "semantic-release"

que foi gerado automaticamente pela CLI do Semantic Release. Precisaremos aprimorar este script da seguinte maneira:

 "semantic-release": "semantic-release --branches main"

Isso indica que os lançamentos serão feitos apenas no branch principal.

Além disso, o Semantic Release gera uma descrição com base no campo repository em seu package.json . Este campo oferece detalhes sobre a localização do código-fonte do pacote.

 "repository": { "type": "git", "url": "https://github.com/<your_github_username>/your_github_repo.git" }

Agora, vamos enviar todas as nossas alterações com:

 git add . && git commit -m "semantic release" && git push

Formato de confirmação

O Semantic Release depende da convenção de mensagens de commit estruturadas para determinar o tipo de aumento de versão (principal, secundário ou patch) e gerar changelogs. Esta convenção de commit é frequentemente chamada de formato “Commits Convencionais”.

Para esta configuração, precisaremos de vários plugins. Certifique-se de que seu package.json contenha o seguinte conteúdo:

 "release": { "branches": [ { "name": "main" } ], "plugins": [ [ "@semantic-release/commit-analyzer", { "releaseRules": [ { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "refactor", "release": "patch" }, { "type": "build", "release": "patch" }, { "type": "chore", "release": "patch" }, { "type": "minor", "release": "patch" } ] } ], "@semantic-release/release-notes-generator", "@semantic-release/npm", "@semantic-release/github", [ "@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" } ] ] }

pacote.json

Para a ferramenta de configuração de formato de commit, usaremos comprometer-se . Para instalá-lo, siga este comando:

 npx commitizen init cz-conventional-changelog --save-dev --save-exact

Este comando levará alguns minutos. Em seguida, atualize seu package.json com um novo script:

 "scripts": { // ... "commit": "cz" },

e é hora de utilizar esse script. Comece executando git add . , execute npm run commit e forneça os detalhes necessários para seu commit.

Aqui está o que parece:

 ? Select the type of change that you're committing: feat: A new feature ? What is the scope of this change (eg component or file name): (press enter to skip) commit ? Write a short, imperative tense description of the change (max 86 chars): (14) add commitizen ? Provide a longer description of the change: (press enter to skip) ? Are there any breaking changes? No ? Does this change affect any open issues? No

Depois disso, faça um git push .

Nas ações do GitHub, você verá que nosso commit falhou porque ainda não instalamos o restante dos pacotes para o processo automatizado de mensagem de commit.

 npm i -D @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/npm @semantic-release/changelog

Uma etapa crucial, muitas vezes esquecida na maioria das referências, é definir as permissões do fluxo de trabalho. Navegue até https://github.com/<your_user_name>/tokky/settings/actions e configure as permissões para permitir que ações do GitHub leiam e gravem.

A seguir, vamos mudar um pouco as coisas. Confirme com uma palavra-chave específica, feat: , seguida de sua mensagem.

 git add . && git commit -m "feat: my feature commit" && git push

Você se lembra do releaseRules dentro do package.json ? Essas regras determinam como incrementamos a versão do lançamento do nosso pacote. Com isso implementado, você pode criar uma solicitação pull usando palavras-chave específicas como feat , fix , refactor e assim por diante. Assim que esta solicitação pull for aprovada e posteriormente mesclada no branch principal, ela iniciará um gatilho. Esse gatilho então ativa a ação do GitHub, automatiza o processo de lançamento e garante que seu pacote seja atualizado perfeitamente.

Pacote publicado

O pacote foi publicado com sucesso e todo o processo foi automatizado para maior eficiência. Para confirmar a publicação, acesse suas configurações de npm https://www.npmjs.com/settings/<your_user_name>/packages e procure na seção de pacotes; lá, você encontrará seu pacote recém-publicado.

Agora, com um comando simples como npx your_package_name hi , você pode ver imediatamente os resultados de nossos testes de desenvolvimento. Além disso, o pacote pode ser instalado globalmente usando o comando npm i -g your_package_name .

Conclusão

Como vimos ao longo deste artigo, embora as configurações iniciais possam estar repletas de desafios, a recompensa está em estabelecer um processo de lançamento simplificado e consistente. Aproveitar o GitHub Actions simplifica essas complexidades, garantindo que os desenvolvedores possam se concentrar na qualidade do código em vez de nas complexidades logísticas.

Quer você esteja apenas começando sua jornada com pacotes públicos ou tenha encontrado contratempos em seus esforços de publicação, há um valor inegável em adotar um fluxo de trabalho estruturado e automatizado. Ao integrar o Semantic Release, você garante um controle de versão consistente e defende uma abordagem futura para o desenvolvimento de software.

Um brinde à publicação perfeita, menos dores de cabeça e mais tempo gasto no aperfeiçoamento do código que impulsiona nosso mundo digital.

Lembre-se de que é essencial que NPM_TOKEN e GITHUB_TOKEN recebam as permissões apropriadas no GitHub Actions. Além disso, seu package.json deve ser configurado corretamente com configurações para acesso publishConfig e garantir que a configuração private esteja definida como false . Se você encontrar algum problema ou tiver ideias, não hesite em comentar.

Referências

Repositório: https://github.com/antonkalik/tokky
CLI de liberação semântica: https://github.com/semantic-release/cli
Comprometido: https://github.com/commitizen/cz-cli