Подробные инструкции по публикации общедоступного пакета без области действия с использованием семантического выпуска с использованием возможностей GitHub Actions.
В условиях меняющейся среды разработки программного обеспечения поддержание согласованности версий и автоматизация процесса выпуска важнее, чем когда-либо. Введите Semantic Release: инструмент, предназначенный для обеспечения четкого и структурированного управления версиями. Для разработчиков, использующих общедоступные пакеты без области действия, этот процесс может показаться устрашающим. Однако, когда у нас под рукой есть возможности GitHub Actions, автоматизация становится проще простого.
В этой статье представлено подробное и всеобъемлющее руководство с пошаговыми инструкциями по плавной интеграции Semantic Release в ваш рабочий процесс, специально предназначенное для тех, кто использует общедоступные пакеты без области действия. Погрузитесь и откройте для себя оптимизированный подход к выпускам программного обеспечения.
Когда я создал свой публичный пакет, я столкнулся с трудностями при его беспрепятственной публикации в NPM. Было непросто обеспечить правильные конфигурации.
Чтобы разобраться в этом, давайте пошагово рассмотрим правильную публикацию общедоступных пакетов в NPM.
Название пакета
Прежде чем приступить к реализации нашего пакета, лучше найти для него подходящее имя. Чтобы быть уверенным, что имя еще не занято — отметьте my_package_name и возьмите его для своего пакета. Я выбрал «токки». С этого момента резервирование имени пакета невозможно. Для имени в npm вам необходимо опубликовать пакет.
Создать пакет
Целью является разработка простого пакета, который выводит контент на консоль. Нам нужно убедиться, что мы сможем установить его и запустить. Для процесса сборки воспользуемся простым esbuild. В этой статье я буду использовать имя пакета 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 должен выглядеть следующим образом:
Дополнительно добавим два файла игнорирования:
и для НПМ:
Наконец, я опишу свою настройку ESLint. Однако помните, что конфигурация может различаться в зависимости от конкретных требований вашего пакета.
Затем перейдите на 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 и заполните его следующим содержимым:
Идея проста: выполнение my_package_name hi должно отобразить «Привет [имя пользователя]». Чтобы проверить эту функциональность, выполните команду непосредственно из вашего репозитория, используя:
node src/index.js hi
Если результат соответствует ожиданиям, пришло время создать исходный код:
npm run build
При успешном выполнении этой команды будет создана папка dist, содержащая минимизированный файл index.js.
Токены
Выполнение семантического выпуска, которое будет определять изменения версий и обрабатывать процесс выпуска на основе сообщений о фиксации, требует, чтобы переменные среды (GITHUB_TOKEN, NPM_TOKEN) работали правильно. Токены извлекаются из секретов GitHub, что гарантирует их конфиденциальность.
Чтобы установить GITHUB_TOKEN, перейдите сюда: https://github.com/settings/tokens
Создайте токен, используя раскрывающийся список. Нажмите на новый токен личного доступа (классический) и установите разрешения, как на картинке. Используйте имя вашего пакета, как показано ниже:
После создания скопируйте значение токена и сохраните его конфиденциальность — крайне важно не передавать его другим. Временно сохраните этот токен в надежном месте, так как он нам вскоре понадобится для CLI Semantic Release.
Чтобы сгенерировать NPM_TOKEN, вам сначала понадобится учетная запись на официальном сайте npm. Если вы еще не зарегистрировались, пройдите процедуру регистрации. После этого перейдите к:
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 и заполните его следующим содержимым:
Этот рабочий процесс запускает событие 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 содержит следующее содержимое:
В качестве инструмента формата фиксации настройки мы будем использовать commitizen. Чтобы установить его, выполните следующую команду:
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 (e.g. 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
Commitizen: https://github .com/commitizen/cz-cli
Want to Connect? If you've encountered any challenges, please share them in the comments of my article, or don't hesitate to reach out to me directly at the following places: GitHub: https://github.com/antonkalik LinkedIn: https://www.linkedin.com/in/antonkalik/ Twitter: https://twitter.com/idedycom Website: https://idedy.com
