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 : 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. Liberación semántica 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 , encontré obstáculos al publicarlo sin problemas en NPM. Fue un desafío garantizar las configuraciones correctas. paquete publico 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 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. my_package_name 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 . Creemos con los datos iniciales. tokky package.json mkdir tokky && cd tokky && npm init -y Después de ejecutar el comando, el sistema generó un archivo predeterminado para el proyecto, que se ve así: 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" } En esta guía, el archivo juega un papel crucial para garantizar la configuración correcta. En este momento, especifiquemos la versión del nodo para nuestro paquete: package.json 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 : Esto designa el punto de entrada principal para el módulo. main : aquí especificará los ejecutables que proporcione su módulo. bin : 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. files : asegúrese de que esté configurado en ya que nuestro paquete está destinado a ser público. private false : El acceso para esto debe establecerse como . publishConfig public Después de estas configuraciones, su debería parecerse al siguiente: 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 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 git@github.com:<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 , genere un archivo y rellénelo con el siguiente contenido: 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 simple para ejemplo de paquete El concepto es sencillo: ejecutar debería mostrar "Hola [nombre de usuario]". my_package_name hi 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 que contiene un archivo minimizado. dist index.js 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 ( , ) para funcionar correctamente. Los tokens se obtienen de los secretos de GitHub, lo que garantiza que permanezcan confidenciales. GITHUB_TOKEN NPM_TOKEN Para configurar , navegue aquí: GITHUB_TOKEN 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 , primero necesita una cuenta en . Si aún no te has registrado, sigue el proceso de registro. Después de eso, navegue hasta: NPM_TOKEN sitio web oficial de npm 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 en los secretos del repositorio: NPM_TOKEN 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 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. CI/CD Para comenzar, cree un directorio en la raíz de su proyecto. Dentro de este directorio, establezca una subcarpeta de . .github workflows Aquí, cree nuestro archivo de configuración llamado y rellénelo con el siguiente contenido: 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 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 usando los tokens designados. npm run semantic-release 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 y ejecútelo en su repositorio: este código GitHub 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 que establecimos previamente en los secretos del repositorio. Si ahora revisa su , la versión se mostrará como: NPM_TOKEN package.json "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 en su . Este campo ofrece detalles sobre la ubicación del código fuente del paquete. repository package.json "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 contenga el siguiente contenido: 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" } ] ] } paquete.json Para la herramienta de formato de confirmación de configuración, usaremos . Para instalarlo, siga este comando: comprometerse npx commitizen init cz-conventional-changelog --save-dev --save-exact Este comando tardará unos minutos. Luego actualice su con un nuevo script: package.json "scripts": { // ... "commit": "cz" }, y es hora de utilizar ese script. Comience ejecutando , luego ejecute y proporcione los detalles necesarios para su confirmación. git add . npm run commit 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 Navegue a y configure los permisos para permitir que las acciones de GitHub lean y escriban. 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. https://github.com/<your_user_name>/tokky/settings/actions A continuación, cambiemos un poco las cosas. Comprométete con una palabra clave específica, seguida de tu mensaje. feat: git add . && git commit -m "feat: my feature commit" && git push ¿Recuerda las dentro del ? 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 , , , 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. releaseRules package.json feat fix refactor 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 y busque en la sección de paquetes; allí encontrará su paquete recién publicado. https://www.npmjs.com/settings/<your_user_name>/packages Ahora, con un comando simple como , puedes ver inmediatamente los resultados de nuestras pruebas de desarrollo. Además, el paquete se puede instalar globalmente usando el comando . npx your_package_name hi 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 como tengan los permisos adecuados dentro de GitHub Actions. Además, su debe estar configurado correctamente con la configuración para el acceso y asegurarse de que la configuración esté configurada en . Si encuentra algún problema o tiene alguna idea, no dude en comentar. NPM_TOKEN GITHUB_TOKEN package.json publishConfig private false Referencias Repositorio: CLI de versión semántica: Comprometido: https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli También publicado . aquí Gracias a Domingo Harper de Unsplash para la imagen principal.
