Cómo implementar la liberación semántica para paquetes públicos sin alcance

Instrucciones detalladas sobre cómo publicar un paquete público sin alcance mediante la versión semántica aprovechando el poder de GitHub Actions

En el cambiante panorama del desarrollo de software, mantener la coherencia de las versiones y automatizar el proceso de lanzamiento es más importante que nunca. Ingresar Liberación semántica : una herramienta diseñada para garantizar un control de versiones claro y estructurado. Para los desarrolladores que aprovechan paquetes públicos sin alcance, el proceso puede parecer desalentador. Sin embargo, con el poder de las acciones de GitHub a nuestro alcance, la automatización se vuelve muy sencilla.

Este artículo ofrece una guía detallada y completa, que proporciona instrucciones paso a paso para integrar perfectamente Semantic Release en su flujo de trabajo, diseñada específicamente para quienes utilizan paquetes públicos sin alcance. Sumérgete y descubre el enfoque optimizado para los lanzamientos de software.

Cuando creé mi paquete publico , encontré obstáculos al publicarlo sin problemas en NPM. Fue un desafío garantizar las configuraciones correctas.

Para concretarlo, repasemos una experiencia paso a paso para publicar paquetes públicos adecuados en MNP .

Descripción general del contenido

• Nombra el paquete
• Crear un paquete
• Fuente del paquete
• Fichas
• Configuración de acciones de GitHub
• liberación semántica
• Formato de confirmación
• Paquete publicado
• Conclusión

Nombra el paquete

Antes de lanzarnos a implementar nuestro paquete, es mejor encontrar el nombre adecuado para él. Para asegurarse de que el nombre no esté en uso, verifique my_package_name y considérelo para su paquete. Elegí "tokky". A partir de ese momento, reservar el nombre del paquete es imposible. Para el nombre en npm, debes publicar el paquete.

Crear un paquete

El objetivo es desarrollar un paquete sencillo que envíe contenido a la consola. Necesitamos asegurarnos de que podemos instalarlo y ejecutarlo. Para el proceso de construcción, usemos simples construir .

Durante este artículo, usaré el nombre del paquete tokky . Creemos package.json con los datos iniciales.

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

Después de ejecutar el comando, el sistema generó un archivo package.json predeterminado para el proyecto, que se ve así:

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

En esta guía, el archivo package.json juega un papel crucial para garantizar la configuración correcta. En este momento, especifiquemos la versión del nodo para nuestro paquete:

 echo "v18" > .nvmrc

y active la versión especificada con lo siguiente:

 nvm use

Para el archivo README.md :

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

Finalmente, instale las dependencias de desarrollo:

 npm i -D esbuild eslint prettier

En nuestra configuración inicial, debemos abordar varios puntos clave en el package.json :

• main : Esto designa el punto de entrada principal para el módulo.
• bin : aquí especificará los ejecutables que proporcione su módulo.
• files : debe contener una serie de patrones de archivos que se incluirán cuando el paquete se empaquete y se publique posteriormente en el registro npm.
• private : asegúrese de que esté configurado en false ya que nuestro paquete está destinado a ser público.
• publishConfig : El acceso para esto debe establecerse como public .

Después de estas configuraciones, su package.json debería parecerse al siguiente:

 { "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 después de la configuración inicial

Además, agreguemos dos archivos ignorados:

 .idea node_modules dist

.gitignore

y para npm:

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

.npmignorar

Por último, describiré mi configuración para ESLint. Sin embargo, recuerde que la configuración puede variar según los requisitos específicos de su paquete.

 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: {}, };

Configuración .eslintrc.js

A continuación, dirígete a GitHub y establece un nuevo repositorio. Ponle el nombre de tu paquete.

Continúe ejecutando los siguientes comandos:

 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

Fuente del paquete

A continuación, diseñemos una aplicación básica y configurémosla para su compilación. Dentro de la carpeta src , genere un archivo index.js y rellénelo con el siguiente contenido:

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

Script simple para ejemplo de paquete

El concepto es sencillo: ejecutar my_package_name hi debería mostrar "Hola [nombre de usuario]".

Para validar esta funcionalidad, ejecute el comando directamente desde su repositorio usando:

 node src/index.js hi

Si el resultado se alinea con las expectativas, es hora de crear la fuente:

 npm run build

La ejecución exitosa de este comando producirá una carpeta dist que contiene un archivo index.js minimizado.

Fichas

La ejecución de la versión semántica, que determinará los cambios de versión y manejará el proceso de liberación en función de los mensajes de confirmación, requiere variables de entorno ( GITHUB_TOKEN , NPM_TOKEN ) para funcionar correctamente. Los tokens se obtienen de los secretos de GitHub, lo que garantiza que permanezcan confidenciales.

Para configurar GITHUB_TOKEN , navegue aquí: https://github.com/settings/tokens

Genere el token usando un menú desplegable. Haga clic en el nuevo token de acceso personal (clásico) y establezca el permiso como en la imagen.

Utilice el nombre de su paquete como se muestra a continuación:

Una vez generado, copie el valor del token y manténgalo confidencial; es fundamental no compartirlo con otros. Guarde temporalmente este token de forma segura, ya que lo necesitaremos en breve para la CLI de versión semántica.

Para generar NPM_TOKEN , primero necesita una cuenta en sitio web oficial de npm . Si aún no te has registrado, sigue el proceso de registro. Después de eso, navegue hasta:

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

y generar un token "clásico" con la opción "publicar".

Copie el valor generado del token y navegue hasta los secretos de GitHub:

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

y ponga un nuevo secreto como NPM_TOKEN en los secretos del repositorio:

Con nuestros secretos ahora configurados, podemos configurar GitHub Actions.

Configuración de acciones de GitHub

Para automatizar nuestros procesos, usaremos GitHub Actions. Esta es una herramienta CI/CD integrada en GitHub. Permite a los desarrolladores automatizar flujos de trabajo directamente desde sus repositorios de GitHub, como crear, probar e implementar aplicaciones. Al definir flujos de trabajo en archivos YAML, los usuarios pueden desencadenar acciones basadas en eventos específicos, como solicitudes de inserción y extracción u horarios programados, lo que hace que el proceso de desarrollo de software sea más eficiente y automatizado.

Para comenzar, cree un directorio .github en la raíz de su proyecto. Dentro de este directorio, establezca una subcarpeta de workflows .

Aquí, cree nuestro archivo de configuración llamado release.yml y rellénelo con el siguiente contenido:

 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 flujo de trabajo desencadena un evento de envío a la rama principal. Está configurado para ejecutar el trabajo en la última máquina virtual Ubuntu que ofrece GitHub. Si bien no es imperativo profundizar en cada trabajo, destaquemos algunos específicos. Hacia el final, observe cómo invocamos npm run semantic-release usando los tokens designados.

liberación semántica

Para el proceso de publicación automatizado, utilizaremos la publicación semántica. Esta herramienta maneja el control de versiones y la publicación de paquetes según la semántica del mensaje de confirmación. Sigue las convenciones de Control de versiones semántico (SemVer) para determinar los cambios de versión (mayor, menor o parche). Al analizar los mensajes de confirmación, se eliminan los pasos manuales del control de versiones, se garantiza que los números de versión sean consistentes y se agiliza el proceso de lanzamiento. Vamos a configurarlo.

Para esa configuración, usaremos este código GitHub y ejecútelo en su repositorio:

 npx semantic-release-cli setup

Y sigue las preguntas:

 % 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

Ya deberías tener tu Token Personal. Simplemente ingréselo cuando se le solicite. De manera similar, las acciones de GitHub que configuramos utilizarán el NPM_TOKEN que establecimos previamente en los secretos del repositorio. Si ahora revisa su package.json , la versión se mostrará como:

 "version": "0.0.0-development",

y nuevo guión:

 "semantic-release": "semantic-release"

que fue generado automáticamente por la CLI de versión semántica. Necesitaremos mejorar este script de la siguiente manera:

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

Esto indica que los lanzamientos solo se realizarán desde la rama principal.

Además, Semantic Release genera una descripción basada en el campo repository en su package.json . Este campo ofrece detalles sobre la ubicación del código fuente del paquete.

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

Ahora, impulsemos todos nuestros cambios con:

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

Formato de confirmación

Semantic Release se basa en la convención de mensajes de confirmación estructurados para determinar el tipo de mejora de versión (mayor, menor o parche) y generar registros de cambios. Esta convención de confirmación a menudo se denomina formato de "compromisos convencionales".

Para esta configuración, necesitaremos varios complementos. Asegúrese de que su package.json contenga el siguiente contenido:

 "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" } ] ] }

paquete.json

Para la herramienta de formato de confirmación de configuración, usaremos comprometerse . Para instalarlo, siga este comando:

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

Este comando tardará unos minutos. Luego actualice su package.json con un nuevo script:

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

y es hora de utilizar ese script. Comience ejecutando git add . , luego ejecute npm run commit y proporcione los detalles necesarios para su confirmación.

Así es como se ve:

 ? 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

Después de eso, haz un git push .

En las acciones de GitHub, verá que nuestra confirmación falló porque todavía no hemos instalado el resto de los paquetes para el proceso de mensajes de confirmación automatizados.

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

Un paso crucial, que a menudo se pasa por alto en la mayoría de las referencias, es configurar los permisos del flujo de trabajo. Navegue a https://github.com/<your_user_name>/tokky/settings/actions y configure los permisos para permitir que las acciones de GitHub lean y escriban.

A continuación, cambiemos un poco las cosas. Comprométete con una palabra clave específica, feat: seguida de tu mensaje.

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

¿Recuerda las releaseRules dentro del package.json ? Estas reglas dictan cómo incrementamos la versión de nuestro paquete. Una vez implementado esto, puede crear una solicitud de extracción utilizando palabras clave específicas como feat , fix , refactor , etc. Una vez que esta solicitud de extracción se apruebe y posteriormente se fusione con la rama principal, se iniciará un activador. Luego, este activador activa la acción de GitHub, automatiza el proceso de lanzamiento y garantiza que su paquete se actualice sin problemas.

Paquete publicado

El paquete se publicó con éxito y todo el proceso se ha automatizado para mayor eficiencia. Para confirmar la publicación, diríjase a la configuración de npm https://www.npmjs.com/settings/<your_user_name>/packages y busque en la sección de paquetes; allí encontrará su paquete recién publicado.

Ahora, con un comando simple como npx your_package_name hi , puedes ver inmediatamente los resultados de nuestras pruebas de desarrollo. Además, el paquete se puede instalar globalmente usando el comando npm i -g your_package_name .

Conclusión

Como hemos visto a lo largo de este artículo, si bien las configuraciones iniciales pueden estar plagadas de desafíos, la recompensa radica en establecer un proceso de lanzamiento optimizado y consistente. Aprovechar GitHub Actions simplifica estas complejidades, garantizando que los desarrolladores puedan centrarse en la calidad del código en lugar de las complejidades logísticas.

Ya sea que recién esté comenzando su viaje con paquetes públicos o haya encontrado contratiempos en sus esfuerzos editoriales, adoptar un flujo de trabajo estructurado y automatizado tiene un valor innegable. Al integrar Semantic Release, garantiza un control de versiones coherente y defiende un enfoque de futuro para el desarrollo de software.

Brindemos por una publicación fluida, menos dolores de cabeza y más tiempo dedicado a perfeccionar el código que impulsa nuestro mundo digital.

Recuerde, es esencial que tanto NPM_TOKEN como GITHUB_TOKEN tengan los permisos adecuados dentro de GitHub Actions. Además, su package.json debe estar configurado correctamente con la configuración para el acceso publishConfig y asegurarse de que la configuración private esté configurada en false . Si encuentra algún problema o tiene alguna idea, no dude en comentar.

Referencias

Repositorio: https://github.com/antonkalik/tokky
CLI de versión semántica: https://github.com/semantic-release/cli
Comprometido: https://github.com/commitizen/cz-cli