Цель: чтобы семантическая версия и npm publish обрабатывались автоматически через мою bitbucketpipeline

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

Я использовал следующие инструменты:

  • Commitizen, cz-конвенциональный журнал изменений
  • Semantic-release, @ semantic-release / changelog, @ semantic-release / commit-analyzer, @ semantic-release / git,
    @ semantic-release / npm, @ semantic-release / release-notes-generator
  • Bitbucket конвейеры

Семантическая версия

Семантическая версия, также известная как SemVer, - это номер вашей версии в виде MAJOR.MINOR.PATCH, например: 2.3.6

ОСНОВНАЯ версия при внесении несовместимых изменений API,

МИНИМАЛЬНАЯ версия, когда вы добавляете функциональность обратно совместимым образом, и

Версия PATCH при исправлении ошибок с обратной совместимостью.

Если вы сделаете критическое изменение, ваше ГЛАВНОЕ число должно увеличиться.

Если вы вносите изменение в функцию, которое не нарушит функциональность вашего пользователя, при загрузке изменения должно увеличиваться только МЕНЬШЕЕ число.

Если вы исправляете ошибки, номер патча увеличится.

Изменения документа не влияют на номер вашей версии.

совершить

Commitizen - это инструмент для коммита git, который позволяет вам использовать приглашение, которое в конечном итоге приведет к написанию вашего сообщения и описания коммита за вас.

cz-конвенциональный-changelog - это шаблон вопросов, которые вам будут задавать при совершении коммита. Вы можете установить другие доступные шаблоны.

Для начала установите commitizen глобально на свой компьютер:

npm install -g commitizen

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

Если вы используете npm 5.2+:

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

это добавляет скрипт в ваш package.json

...
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }

затем вручную добавьте в свой package.json

"scripts": {
    "commit": "git-cz"
},

теперь, когда вы запустите npm run commit, он будет следовать подсказке шаблона вашего журнала изменений и генерировать сообщение о фиксации git. Вы можете использовать justs git-cz, но npm run commit легче запомнить.

Таким образом, поток будет заключаться в том, чтобы добавить файлы, которые вы хотите для фиксации, запустить git-cz и git push.

git add . 
npm run commit
... //go through your changelog
git push

Что вы получите, если воспользуетесь cz-conventional-changelog:

Ваше сообщение фиксации будет иметь этот формат type(scope):short description

Тогда ваша фиксация будет иметь следующее описание:

long description
BREAKING CHANGE: breaking change description
issue number link

Примечание. ЛОМАЮЩИЕ ИЗМЕНЕНИЯ отображаются только в том случае, если на критические изменения дан ответ "да".

Примечание. Номер проблемы отображается только в том случае, если вы ответили утвердительно на вопрос Does this change affect any open issues?, а затем передали идентификатор проблемы.

Поскольку я использую bitbucket, мой идентификатор задачи автоматически создает ссылку на мой тикет Jira https://<domain>.atlassian.net/browse/<ticketId>. Когда я нажимаю ссылку, она автоматически откроет соответствующую заявку в модальном окне.

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

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

Документацию по семантическому релизу можно найти здесь.

npm install --save-dev semantic-release

установить другие необходимые пакеты

npm install --save-dev @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/npm @semantic-release/changelog @semantic-release/git

Добавьте в свой package.json следующее:

"release": {
  "repositoryUrl": "https://[email protected]/<BITBUCKET_REPO_OWNER>/<BITBUCKET_REPO_SLUG>.git",
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    "@semantic-release/changelog",
    "@semantic-release/git"
  ]
},

примечание: вам необходимо изменить <BITBUCKET_REPO_OWNER> и <BITBUCKET_REPO_SLUG>, чтобы они соответствовали репозиторию вашего проекта. (Если вы попытаетесь клонировать свой репозиторий, последние два раздела вашего пути составляют владельца репо и слаг репо.)

Ex: git clone https://[email protected]/blahblah/sampleproject.git

BITBUCKET_REPO_OWNER - это blahblah, а BITBUCKET_REPO_SLUG - sampleproject

Теперь нам нужно настроить наши учетные данные для:

  1. включить конвейеры битбакета для нашего репо
  2. разрешить Bitbucket публиковать в собственном репо
  3. опубликовать в npm

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

Настройка Bitbucket Pipeline

создайте bitbucket-pipelines.yml

touch bitbucket-pipelines.yml

См. Документацию по параметрам конфигурации конвейера битбакета здесь. Документация по npm для bitbucket доступна здесь (вы сможете найти файл bitbucket-pipelines.yml по умолчанию).

Мой bitbucket-pipelines.yml выглядит так:

image: node:latest

pipelines:
  branches:
    master:
      - step:
          caches:
            - node
          script: 
            # Get an oauth access token using the client credentials, parsing out the token with jq.
            - apt-get update && apt-get install -y curl jq
            - >
              export BB_TOKEN=$(curl -s -X POST -u "${CLIENT_ID}:${CLIENT_SECRET}" \
                https://bitbucket.org/site/oauth2/access_token \
                -d grant_type=client_credentials -d scopes="repository"| jq --raw-output '.access_token')
            # Configure git to use the oauth token. This well happen when setting env variable BB_TOKEN
            - npm install
            - rm -rf ./build && npm run build
# if you have test script in your package.json
            - npm run test
            - npx semantic-release --debug

как только вы зафиксируете файл bitbucket-pipelines.yml, вы сможете перейти к настройкам ›конвейеров и включить конвейер битбакета.

Примечание: мой package.json содержит сценарий сборки для webpack и публикуется в ./build, поэтому я запускаю rm -rf ./build && npm run build

"scripts": {
  "build": "webpack --mode production"
},

Публикация Bitbucket Cloud в собственное репо с использованием семантического выпуска

Я часами искал в Google, как заставить это работать с семантическим выпуском.

Согласно этой статье ваш пайплайн якобы может публиковать для себя, однако я не смог.

Я попытался использовать ключ SSH проекта и ключ доступа (также известный как ключ развертывания). Разница между ними хорошо видна здесь.

Ключ доступа к вашему проекту (также известный как ключ развертывания) не имеет возможности записи, даже если вы предоставите все возможные разрешения. Вы получите сообщение «В доступе к репозиторию отказано. доступ через ключ развертывания доступен только для чтения ».

Также в облаке bitbucket нет токенов личного доступа. Посмотреть здесь".

В итоге мне пришлось использовать токены доступа, упомянутые в разделе Oauth.

Создайте OAuth, выбрав свой аватар ›Настройки Bitbucket› OAuth и нажав Добавить потребителя.

Дайте своему Oauth имя, скопируйте и вставьте https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token в URL-адрес обратного вызова точно так же, как в скобках, и все такое.

{client_id} будет ссылаться на клиентский ключ oauth, который вы создадите ниже.

Дайте репозиторию права на чтение и запись:

Если вы откроете данные о потребителе OAuth, вы найдете свой ключ и секрет потребителя. Вот тот, который я создал в качестве примера того, что вы ожидаете увидеть:

Добавьте его в переменные конвейера битбакета.

В битбакете Settings > pipelines > repository variable, где CLIENT_ID - значение из ключа, а CLIENT_SECRET - значение из секрета

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

Это значение передается BB_TOKEN, необходимому для семантического выпуска, через сценарий, показанный ранее в bitbucket-pipelines.yml. Это был код, который сделал это:

export BB_TOKEN=$(curl -s -X POST -u "${CLIENT_ID}:${CLIENT_SECRET}" \
                https://bitbucket.org/site/oauth2/access_token \
                -d grant_type=client_credentials -d scopes="repository"| jq --raw-output '.access_token')

Создать токен npm

Для публикации в npm вам необходимо создать токен npm с помощью npm-token. Запустить:

npm token create

Скопируйте переменную токена и добавьте ее в свой Settings > pipelines > repository variable с именем NPM_TOKEN. Обязательно зафиксируйте свое значение, чтобы никто не мог его увидеть.

Настройка завершена

Итак, теперь, когда вы запустите npm run commit и внесете изменения, вы

  • иметь стандартное сообщение коммита git
  • получить конвейеры битбакета для запуска семантического выпуска
  • Если семантический -release видит слова BREAKING CHANGE, это увеличит ГЛАВНЫЙ номер вашего package.json.
  • он отправит изменение в ваше репо, используя ваши учетные данные Oauth, а затем опубликует в npm

Примечание: я заметил, что часто забываю вытащить изменения при фиксации, поэтому я изменил свой скрипт фиксации в package.json, чтобы проверить, не отстает ли моя ветка, и если да, то вместо запуска git-cz 

"commit": "changed=0 \ngit remote update && git status -uno | grep -q 'Your branch is behind' && changed=1\nif [ $changed = 1 ]; then\n    echo \"***WARNING***\n pull latest\";\nelse\n git-cz\nfi",

Виола, у вас есть автоматическое управление версиями пакетов и настройка фиксации.