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 : 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. Liberação Semântica 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 , encontrei obstáculos para publicá-lo perfeitamente no NPM. Foi um desafio garantir as configurações corretas. pacote público 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 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. my_package_name 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 . Vamos criar com os dados iniciais. tokky package.json mkdir tokky && cd tokky && npm init -y Após executar o comando, o sistema gerou um arquivo padrão para o projeto, que se parece com este: package.json { "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 desempenha um papel crucial para garantir a configuração correta. Neste momento, vamos especificar a versão do nó para nosso pacote: package.json 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 : designa o ponto de entrada principal do módulo. main : aqui você especificará quaisquer executáveis fornecidos pelo seu módulo. bin : 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. files : certifique-se de que esteja definido como , pois nosso pacote deve ser público. private false : O acesso para isso deve ser definido como . publishConfig public Após essas configurações, seu deverá se parecer com o seguinte: package.json { "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": "antonkalik@gmail.com", "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 git@github.com:<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 , gere um arquivo e preencha-o com o seguinte conteúdo: src index.js #!/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 deve exibir “Hello [nome de usuário]”. my_package_name hi 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 contendo um arquivo reduzido. dist index.js 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 ( , ) para operar corretamente. Os tokens são obtidos dos segredos do GitHub, garantindo que permaneçam confidenciais. GITHUB_TOKEN NPM_TOKEN Para definir , navegue aqui: GITHUB_TOKEN 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 , primeiro você precisa de uma conta no . Se você ainda não se cadastrou, passe pelo processo de cadastro. Depois disso, navegue até: NPM_TOKEN Site oficial do npm 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 nos segredos do repositório: NPM_TOKEN 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 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. CI/CD Para começar, crie um diretório na raiz do seu projeto. Dentro deste diretório, estabeleça uma subpasta . .github workflows Aqui, crie nosso arquivo de configuração chamado e preencha-o com o seguinte conteúdo: release.yml 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 usando os tokens designados. npm run semantic-release 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 e execute-o em seu repositório: este código GitHub 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 que estabelecemos anteriormente nos segredos do repositório. Se você verificar agora seu , a versão será exibida como: NPM_TOKEN package.json "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 em seu . Este campo oferece detalhes sobre a localização do código-fonte do pacote. repository package.json "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 contenha o seguinte conteúdo: package.json "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 . Para instalá-lo, siga este comando: comprometer-se npx commitizen init cz-conventional-changelog --save-dev --save-exact Este comando levará alguns minutos. Em seguida, atualize seu com um novo script: package.json "scripts": { // ... "commit": "cz" }, e é hora de utilizar esse script. Comece executando , execute e forneça os detalhes necessários para seu commit. git add . npm run 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 Navegue até e configure as permissões para permitir que ações do GitHub leiam e gravem. Uma etapa crucial, muitas vezes esquecida na maioria das referências, é definir as permissões do fluxo de trabalho. https://github.com/<your_user_name>/tokky/settings/actions A seguir, vamos mudar um pouco as coisas. Confirme com uma palavra-chave específica, , seguida de sua mensagem. feat: git add . && git commit -m "feat: my feature commit" && git push Você se lembra do dentro do ? 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 , , 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. releaseRules package.json feat fix refactor 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 e procure na seção de pacotes; lá, você encontrará seu pacote recém-publicado. https://www.npmjs.com/settings/<your_user_name>/packages Agora, com um comando simples como , você pode ver imediatamente os resultados de nossos testes de desenvolvimento. Além disso, o pacote pode ser instalado globalmente usando o comando . npx your_package_name hi 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 e recebam as permissões apropriadas no GitHub Actions. Além disso, seu deve ser configurado corretamente com configurações para acesso e garantir que a configuração esteja definida como . Se você encontrar algum problema ou tiver ideias, não hesite em comentar. NPM_TOKEN GITHUB_TOKEN package.json publishConfig private false Referências Repositório: CLI de liberação semântica: Comprometido: https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli Também publicado . aqui Graças a Domingo Harpista do Unsplash para a imagem principal.
