Подробные инструкции по публикации общедоступного пакета без области действия с использованием семантического выпуска с использованием возможностей GitHub Actions. В условиях меняющейся среды разработки программного обеспечения поддержание согласованности версий и автоматизация процесса выпуска важнее, чем когда-либо. Входить : инструмент, предназначенный для обеспечения четкого и структурированного управления версиями. Для разработчиков, использующих общедоступные пакеты без области действия, этот процесс может показаться устрашающим. Однако, когда у нас под рукой есть возможности действий GitHub, автоматизация становится проще простого. Семантический релиз В этой статье представлено подробное и всеобъемлющее руководство с пошаговыми инструкциями по плавной интеграции Semantic Release в ваш рабочий процесс, специально предназначенное для тех, кто использует общедоступные пакеты без области действия. Погрузитесь и откройте для себя оптимизированный подход к выпускам программного обеспечения. Когда я создал свой , я столкнулся с препятствиями при беспрепятственной публикации его в NPM. Было непросто обеспечить правильные конфигурации. общественный пакет Чтобы закрепить это, давайте пошагово рассмотрим правильную публикацию общедоступных пакетов для . НПМ Обзор контента Назовите пакет Создать пакет Источник пакета Токены Настройка действий GitHub Семантический выпуск Формат фиксации Опубликованный пакет Заключение Назовите пакет Прежде чем приступить к реализации нашего пакета, лучше найти для него подходящее имя. Чтобы убедиться, что имя еще не занято — проверьте и возьмите его для своего пакета. Я выбрал «токки». С этого момента резервирование имени пакета невозможно. Для имени в npm вам необходимо опубликовать пакет. my_package_name Создать пакет Целью является разработка простого пакета, который выводит контент на консоль. Нам нужно убедиться, что мы сможем установить его и запустить. Для процесса сборки давайте воспользуемся простым . эсбилд В этой статье я буду использовать имя пакета . Создадим с исходными данными. 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 : должен содержать массив шаблонов файлов, которые будут включены при упаковке пакета и последующей публикации в реестре npm. files : убедитесь, что для этого параметра установлено значение , поскольку наш пакет должен быть общедоступным. 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": "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 после первоначальной настройки Дополнительно добавим два файла игнорирования: .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 git@github.com:<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}`); } Простой скрипт для примера пакета Идея проста: выполнение должно отобразить «Hello [имя пользователя]». my_package_name hi Чтобы проверить эту функциональность, выполните команду непосредственно из вашего репозитория, используя: node src/index.js hi Если результат соответствует ожиданиям, пришло время создать исходный код: npm run build Успешное выполнение этой команды создаст папку , содержащую минимизированный файл . dist index.js Токены Выполнение семантического выпуска, которое будет определять изменения версий и обрабатывать процесс выпуска на основе сообщений о фиксации, требует, чтобы переменные среды ( , ) работали правильно. Токены извлекаются из секретов GitHub, что гарантирует их конфиденциальность. GITHUB_TOKEN NPM_TOKEN Чтобы установить , перейдите сюда: 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. Это инструмент , интегрированный в GitHub. Он позволяет разработчикам автоматизировать рабочие процессы непосредственно из своих репозиториев GitHub, такие как сборка, тестирование и развертывание приложений. Определяя рабочие процессы в файлах YAML, пользователи могут запускать действия на основе определенных событий, таких как запросы push и pull или запланированное время, что делает процесс разработки программного обеспечения более эффективным и автоматизированным. CI/CD Для начала создайте каталог в корне вашего проекта. В этом каталоге создайте подпапку . .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 Перейдите по адресу и настройте разрешения, позволяющие действиям GitHub читать и записывать. Важнейшим шагом, который часто упускают из виду в большинстве ссылок, является установка разрешений рабочего процесса. https://github.com/<your_user_name>/tokky/settings/actions Далее давайте немного изменим ситуацию. Зафиксируйте, указав определенное ключевое слово , за которым следует ваше сообщение. feat: git add . && git commit -m "feat: my feature commit" && git push Вы помните в ? Эти правила определяют, как мы увеличиваем версию выпуска нашего пакета. Имея это в виду, вы можете создать запрос на включение, используя определенные ключевые слова, такие как , , и т. д. Как только этот запрос на включение будет одобрен и впоследствии объединен с основной веткой, он инициирует триггер. Затем этот триггер активирует действие GitHub, автоматизирует процесс выпуска и обеспечивает беспрепятственное обновление вашего пакета. releaseRules package.json feat fix refactor Опубликованный пакет Пакет был успешно опубликован, и весь процесс был автоматизирован для повышения эффективности. Чтобы подтвердить публикацию, перейдите в настройки 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, вы обеспечиваете согласованное управление версиями и продвигаете перспективный подход к разработке программного обеспечения. За беспрепятственную публикацию, меньше головной боли и больше времени, потраченного на совершенствование кода, который двигает наш цифровой мир вперед. Помните, что очень важно, чтобы и , и имели соответствующие разрешения в действиях GitHub. Кроме того, ваш должен быть правильно настроен с настройками доступа и убедиться, что для конфигурации установлено значение . Если у вас возникнут какие-либо проблемы или у вас есть идеи, пожалуйста, не стесняйтесь комментировать. NPM_TOKEN GITHUB_TOKEN package.json publishConfig private false Рекомендации Репозиторий: Семантический релиз CLI: Коммьюнити: https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli Также опубликовано . здесь Благодаря Харпер Сандей из Unsplash для главного изображения.
