Как реализовать семантический выпуск для общедоступных пакетов без области действия

Подробные инструкции по публикации общедоступного пакета без области действия с использованием семантического выпуска с использованием возможностей GitHub Actions.

В условиях меняющейся среды разработки программного обеспечения поддержание согласованности версий и автоматизация процесса выпуска важнее, чем когда-либо. Входить Семантический релиз : инструмент, предназначенный для обеспечения четкого и структурированного управления версиями. Для разработчиков, использующих общедоступные пакеты без области действия, этот процесс может показаться устрашающим. Однако, когда у нас под рукой есть возможности действий GitHub, автоматизация становится проще простого.

В этой статье представлено подробное и всеобъемлющее руководство с пошаговыми инструкциями по плавной интеграции Semantic Release в ваш рабочий процесс, специально предназначенное для тех, кто использует общедоступные пакеты без области действия. Погрузитесь и откройте для себя оптимизированный подход к выпускам программного обеспечения.

Когда я создал свой общественный пакет , я столкнулся с препятствиями при беспрепятственной публикации его в NPM. Было непросто обеспечить правильные конфигурации.

Чтобы закрепить это, давайте пошагово рассмотрим правильную публикацию общедоступных пакетов для НПМ .

Обзор контента

• Назовите пакет
• Создать пакет
• Источник пакета
• Токены
• Настройка действий GitHub
• Семантический выпуск
• Формат фиксации
• Опубликованный пакет
• Заключение

Назовите пакет

Прежде чем приступить к реализации нашего пакета, лучше найти для него подходящее имя. Чтобы убедиться, что имя еще не занято — проверьте my_package_name и возьмите его для своего пакета. Я выбрал «токки». С этого момента резервирование имени пакета невозможно. Для имени в npm вам необходимо опубликовать пакет.

Создать пакет

Целью является разработка простого пакета, который выводит контент на консоль. Нам нужно убедиться, что мы сможем установить его и запустить. Для процесса сборки давайте воспользуемся простым эсбилд .

В этой статье я буду использовать имя пакета tokky . Создадим package.json с исходными данными.

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

После выполнения команды система сгенерировала для проекта файл 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" }

В этом руководстве файл package.json играет решающую роль в обеспечении правильной конфигурации. На этом этапе давайте укажем версию узла для нашего пакета:

 echo "v18" > .nvmrc

и активируйте указанную версию следующим образом:

 nvm use

Для файла README.md :

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

Наконец, установите зависимости разработки:

 npm i -D esbuild eslint prettier

В нашей первоначальной конфигурации нам необходимо учесть несколько ключевых моментов в package.json :

• main : определяет основную точку входа в модуль.
• bin : здесь вы указываете все исполняемые файлы, которые предоставляет ваш модуль.
• files : должен содержать массив шаблонов файлов, которые будут включены при упаковке пакета и последующей публикации в реестре npm.
• private : убедитесь, что для этого параметра установлено значение false , поскольку наш пакет должен быть общедоступным.
• publishConfig : доступ для этого должен быть установлен как public .

После этих настроек ваш 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": "[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 после первоначальной настройки

Дополнительно добавим два файла игнорирования:

 .idea node_modules dist

.gitignore

и для НПМ:

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

.npmignore

Наконец, я опишу свою настройку ESLint. Однако помните, что конфигурация может различаться в зависимости от конкретных требований вашего пакета.

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

Конфигурация .eslintrc.js

Затем перейдите на GitHub и создайте новый репозиторий. Назовите его в честь вашего пакета.

Продолжайте выполнять следующие команды:

 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

Источник пакета

Далее давайте создадим базовое приложение и настроим его для сборки. Внутри папки 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}`); }

Простой скрипт для примера пакета

Идея проста: выполнение my_package_name hi должно отобразить «Hello [имя пользователя]».

Чтобы проверить эту функциональность, выполните команду непосредственно из вашего репозитория, используя:

 node src/index.js hi

Если результат соответствует ожиданиям, пришло время создать исходный код:

 npm run build

Успешное выполнение этой команды создаст папку dist , содержащую минимизированный файл index.js .

Токены

Выполнение семантического выпуска, которое будет определять изменения версий и обрабатывать процесс выпуска на основе сообщений о фиксации, требует, чтобы переменные среды ( GITHUB_TOKEN , NPM_TOKEN ) работали правильно. Токены извлекаются из секретов GitHub, что гарантирует их конфиденциальность.

Чтобы установить GITHUB_TOKEN , перейдите сюда: https://github.com/settings/токены

Создайте токен, используя раскрывающийся список. Нажмите на новый токен личного доступа (классический) и установите разрешения, как на картинке.

Используйте имя вашего пакета, как показано ниже:

После создания скопируйте значение токена и сохраните его конфиденциальность — крайне важно не передавать его другим. Временно сохраните этот токен в надежном месте, так как он нам вскоре понадобится для CLI Semantic Release.

Чтобы сгенерировать NPM_TOKEN , вам сначала понадобится учетная запись на официальный сайт НПМ . Если вы еще не зарегистрировались, пройдите процедуру регистрации. После этого перейдите к:

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

и сгенерируйте «классический» токен с опцией «публиковать».

Скопируйте сгенерированное значение токена и перейдите к секретам GitHub:

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

и поместите новый секрет как NPM_TOKEN в секреты репозитория:

Теперь, когда наши секреты настроены, мы можем настроить действия GitHub.

Настройка действий GitHub

Чтобы автоматизировать наши процессы, мы собираемся использовать GitHub Actions. Это инструмент CI/CD , интегрированный в GitHub. Он позволяет разработчикам автоматизировать рабочие процессы непосредственно из своих репозиториев GitHub, такие как сборка, тестирование и развертывание приложений. Определяя рабочие процессы в файлах YAML, пользователи могут запускать действия на основе определенных событий, таких как запросы push и pull или запланированное время, что делает процесс разработки программного обеспечения более эффективным и автоматизированным.

Для начала создайте каталог .github в корне вашего проекта. В этом каталоге создайте подпапку workflows .

Здесь создайте наш файл конфигурации с именем 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 }}

Этот рабочий процесс запускает событие push в основную ветку. Он настроен для запуска задания на последней виртуальной машине Ubuntu, которую предлагает GitHub. Хотя нет необходимости вникать в каждую работу, давайте выделим некоторые конкретные. В конце обратите внимание, как мы вызываем npm run semantic-release , используя назначенные токены.

Семантический выпуск

Для автоматизированного процесса выпуска мы собираемся использовать Semantic Release. Этот инструмент управляет версиями и публикацией пакетов на основе семантики сообщений о фиксации. Он следует соглашениям семантического управления версиями (SemVer) для определения изменений версий (основных, второстепенных или исправлений). Анализируя сообщения о фиксации, он исключает необходимость ручного управления версиями, обеспечивает согласованность номеров версий и оптимизирует процесс выпуска. Давайте настроим это.

Для этой настройки мы будем использовать этот код GitHub и запустите его в своем репозитории:

 npx semantic-release-cli setup

И следуйте вопросам:

 % 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

У вас уже должен быть личный токен. Просто введите его при появлении запроса. Аналогично, настроенные нами действия GitHub будут использовать NPM_TOKEN , который мы ранее установили в секретах репозитория. Если вы сейчас проверите свой package.json , версия будет отображаться как:

 "version": "0.0.0-development",

и новый скрипт:

 "semantic-release": "semantic-release"

который был автоматически создан с помощью интерфейса командной строки Semantic Release. Нам нужно улучшить этот скрипт следующим образом:

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

Это указывает на то, что релизы будут выпускаться только из основной ветки.

Кроме того, Semantic Release генерирует описание на основе поля repository в вашем package.json . В этом поле содержится подробная информация о местоположении исходного кода пакета.

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

Теперь давайте внесем все наши изменения с помощью:

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

Формат фиксации

Семантический выпуск основан на соглашении о структурированных сообщениях о фиксации для определения типа обновления версии (основное, второстепенное или исправление) и создания журналов изменений. Это соглашение о фиксации часто называют форматом «Обычных коммитов».

Для этой конфигурации нам понадобится несколько плагинов. Убедитесь, что ваш 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" } ] ] }

пакет.json

Для инструмента формата фиксации настройки мы будем использовать совершить . Чтобы установить его, выполните следующую команду:

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

Эта команда займет несколько минут. Затем обновите package.json новым скриптом:

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

и пришло время использовать этот сценарий. Начните с выполнения git add . , затем запустите npm run commit и укажите необходимые сведения для вашего коммита.

Вот как это выглядит:

 ? 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

После этого выполните git push .

В действиях GitHub вы увидите, что наша фиксация не удалась, поскольку мы до сих пор не установили остальные пакеты для процесса автоматического сообщения о фиксации.

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

Важнейшим шагом, который часто упускают из виду в большинстве ссылок, является установка разрешений рабочего процесса. Перейдите по адресу https://github.com/<your_user_name>/tokky/settings/actions и настройте разрешения, позволяющие действиям GitHub читать и записывать.

Далее давайте немного изменим ситуацию. Зафиксируйте, указав определенное ключевое слово feat: , за которым следует ваше сообщение.

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

Вы помните releaseRules в package.json ? Эти правила определяют, как мы увеличиваем версию выпуска нашего пакета. Имея это в виду, вы можете создать запрос на включение, используя определенные ключевые слова, такие как feat , fix , refactor и т. д. Как только этот запрос на включение будет одобрен и впоследствии объединен с основной веткой, он инициирует триггер. Затем этот триггер активирует действие GitHub, автоматизирует процесс выпуска и обеспечивает беспрепятственное обновление вашего пакета.

Опубликованный пакет

Пакет был успешно опубликован, и весь процесс был автоматизирован для повышения эффективности. Чтобы подтвердить публикацию, перейдите в настройки npm https://www.npmjs.com/settings/<your_user_name>/packages и просмотрите раздел пакетов; там вы найдете свой недавно опубликованный пакет.

Теперь с помощью простой команды, например npx your_package_name hi , вы можете сразу увидеть результаты наших тестов разработки. Кроме того, пакет можно установить глобально с помощью команды npm i -g your_package_name .

Заключение

Как мы видели в этой статье, хотя первоначальная настройка может быть сопряжена с трудностями, награда заключается в создании оптимизированного и последовательного процесса выпуска. Использование GitHub Actions упрощает эти сложности, гарантируя, что разработчики смогут сосредоточиться на качестве кода, а не на логистических сложностях.

Независимо от того, начинаете ли вы свой путь с общедоступными пакетами или столкнулись с неудачами в своих издательских усилиях, внедрить структурированный автоматизированный рабочий процесс неоспоримо полезно. Интегрируя Semantic Release, вы обеспечиваете согласованное управление версиями и продвигаете перспективный подход к разработке программного обеспечения.

За беспрепятственную публикацию, меньше головной боли и больше времени, потраченного на совершенствование кода, который двигает наш цифровой мир вперед.

Помните, что очень важно, чтобы и NPM_TOKEN , и GITHUB_TOKEN имели соответствующие разрешения в действиях GitHub. Кроме того, ваш package.json должен быть правильно настроен с настройками доступа publishConfig и убедиться, что для private конфигурации установлено значение false . Если у вас возникнут какие-либо проблемы или у вас есть идеи, пожалуйста, не стесняйтесь комментировать.

Рекомендации

Репозиторий: https://github.com/antonkalik/tokky
Семантический релиз CLI: https://github.com/semantic-release/cli
Коммьюнити: https://github.com/commitizen/cz-cli