Как создать запрос на включение изменений в Homebrew

Следующие команды используются участниками Homebrew, чтобы создать форк Git-репозитория Homebrew на GitHub, создать новую ветку и открыть запрос на включение изменений («PR») из этой ветки.

Тип изменений, которые вы хотите внести, определяет, в какой из основных репозиториев Homebrew нужно отправить запрос на включение изменений. Если вы хотите внести изменения в основной код Homebrew (реализацию brew), откройте запрос на включение изменений в Homebrew/brew. Если вы хотите внести изменения в формулу, откройте запрос на включение изменений в tap homebrew/core, а если изменения касаются кэска — в tap homebrew/cask или другой официальный tap, в зависимости от типа формулы.

Отправка новой версии существующей формулы

1. Используйте brew bump-formula-pr, чтобы выполнить всё одной командой (то есть создать форк, зафиксировать изменения и отправить их). Запустите brew bump-formula-pr --help, чтобы узнать больше.

Отправка новой версии существующего кэска

1. Используйте brew bump-cask-pr, чтобы выполнить всё одной командой (то есть создать форк, зафиксировать изменения и отправить их). Запустите brew bump-cask-pr --help, чтобы узнать больше.

Настройка собственного форка репозитория Homebrew

Запрос на включение изменений в основной код brew

1. Создайте форк репозитория Homebrew/brew на GitHub.
   • Будет создан личный удалённый репозиторий, в который вы сможете отправлять изменения. Это необходимо, поскольку отправлять изменения в основные репозитории могут только сопровождающие Homebrew.

2. Перейдите в каталог, содержащий вашу установку Homebrew:

   cd "$(brew --repository)"

3. Добавьте свой форк, в который можно отправлять изменения, как новый удалённый репозиторий:

   git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/brew.git

   • <YOUR_USERNAME> — это ваше имя пользователя на GitHub, а не имя пользователя на локальном компьютере.

Запрос на включение изменений, связанных с формулами

Прежде чем создавать новую формулу, прочитайте Допустимые формулы.

1. Создайте форк репозитория Homebrew/homebrew-core на GitHub.
   • Будет создан личный удалённый репозиторий, в который вы сможете отправлять изменения. Это необходимо, поскольку отправлять изменения в основные репозитории могут только сопровождающие Homebrew.

2. Добавьте tap (загрузите локальную копию) репозитория основных формул Homebrew:

   brew tap --force homebrew/core

3. Перейдите в каталог, содержащий формулы Homebrew:

   cd "$(brew --repository homebrew/core)"

4. Добавьте свой форк, в который можно отправлять изменения, как новый удалённый репозиторий:

   git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-core.git

   • <YOUR_USERNAME> — это ваше имя пользователя на GitHub, а не имя пользователя на локальном компьютере.

Запрос на включение изменений, связанных с кэсками

Прежде чем создавать новый кэск, прочитайте Допустимые кэски.

1. Создайте форк репозитория Homebrew/homebrew-cask на GitHub.
   • Будет создан личный удалённый репозиторий, в который вы сможете отправлять изменения. Это необходимо, поскольку отправлять изменения в основные репозитории могут только сопровождающие Homebrew.

2. Добавьте tap (загрузите локальную копию) репозитория основных кэсков Homebrew:

   brew tap --force homebrew/cask

3. Перейдите в каталог, содержащий кэски Homebrew:

   cd "$(brew --repository homebrew/cask)"

4. Добавьте свой форк, в который можно отправлять изменения, как новый удалённый репозиторий:

   git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-cask.git

   • <YOUR_USERNAME> — это ваше имя пользователя на GitHub, а не имя пользователя на локальном компьютере.

Создание запроса на включение изменений из новой ветки

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

1. Переключитесь на ветку main:

   git checkout main

2. Получите последние изменения ветки main:

   brew update

3. Создайте новую ветку на основе последней версии ветки по умолчанию:

   git checkout -b <YOUR_BRANCH_NAME> origin/HEAD

4. Внесите изменения. Для формул и кэсков используйте brew edit или любой удобный вам текстовый редактор, руководствуясь рекомендациями из Руководства по формулам или Руководства по кэскам.
   • Если в формуле есть блок bottle do, не удаляйте и не изменяйте его: мы обновим его при включении вашего PR.

5. Проверьте внесённые изменения, выполнив следующие команды, и убедитесь, что все они завершаются без ошибок. brew lgtm --online запускает соответствующие онлайн-проверки brew audit для изменённых и новых формул и кэсков, а также запускает brew test для формул, если установлена последняя версия.

   Для формул:

   HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <FORMULA>
   brew lgtm --online

   Для кэсков:

   HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <CASK>
   brew uninstall --cask <CASK>
   brew lgtm --online

6. Создайте отдельный коммит для каждой изменённой формулы с помощью git add и git commit. Коммиты для каждой формулы необходимо объединить.
   • Обратите внимание: для простых обновлений версий требуется следующий формат сообщения коммита: «<FORMULA_NAME> <NEW_VERSION>», например «source-highlight 3.1.8».

7. Отправьте ветку с новыми коммитами в свой форк:

   git push --set-upstream <YOUR_USERNAME> <YOUR_BRANCH_NAME>

8. Перейдите в соответствующий репозиторий (например, https://github.com/Homebrew/brew, https://github.com/Homebrew/homebrew-core и т. д.) и создайте запрос на включение изменений, чтобы запросить проверку и включение коммитов из отправленной вами ветки. Объясните, зачем нужны изменения, а если исправляете ошибку — как её воспроизвести. Убедитесь, что выполнили все пункты контрольного списка, появившегося в вашем новом PR.
9. Дождитесь отзыва или включения изменений сопровождающими Homebrew. Обычно мы отвечаем на все PR в течение нескольких дней, но в зависимости от загруженности сопровождающих ожидание может занять до недели.

Спасибо!

Использование «искусственного интеллекта» и больших языковых моделей (ИИ/БЯМ)

Вы можете создавать задачи и запросы на включение изменений с помощью ИИ/БЯМ при соблюдении следующих требований (принципы, лежащие в их основе, описаны в документе Ответственное использование ИИ):

• В первоначальном описании задачи или запроса на включение изменений необходимо указать, что вы использовали ИИ/БЯМ, а также назвать использованный инструмент, модель и т. д.
• Прежде чем просить кого-либо из команды Homebrew проверить результат, необходимо проверить весь код, текст и другой контент, созданный ИИ/БЯМ.
• Вы должны быть готовы ответить на все замечания по проверке запроса на включение изменений, вручную, если ИИ/БЯМ не может сделать это за вас.
• Если вы понимаете, что не хотите или не можете выполнить перечисленные выше требования, закройте свою задачу или запрос на включение изменений.

Дальнейшие действия

Чтобы правильно реагировать на отзывы:

1. Попросите разъяснить всё, что вам непонятно, и помочь со всем, что вы не знаете, как сделать.
2. Оставьте комментарий к своему запросу на включение изменений, если внесли все запрошенные изменения или предоставили всю запрошенную информацию, но запрос не включили в течение недели. Если вы зашли в тупик и вам нужна помощь, также оставьте комментарий к своему запросу. Метка needs response на PR означает, что сопровождающие Homebrew ждут вашего ответа на предыдущие комментарии.
3. Обсуждайте изменения в запросе на включение изменений, если только вас не попросили об ином (то есть не пишите сопровождающим личные письма).
4. Не продолжайте обсуждение в закрытых запросах на включение изменений.
5. Не спорьте с сопровождающими Homebrew. Вы можете быть не согласны, но, если они не изменят своего мнения, выполните их просьбу. В конечном счёте именно они решают, что войдёт в Homebrew, поскольку им предстоит поддерживать все внесённые изменения.

Чтобы внести изменения с учётом отзывов:

1. Снова переключитесь на свою ветку:

   git checkout <YOUR_BRANCH_NAME>

2. Внесите все запрошенные изменения и зафиксируйте их с помощью git add и git commit.

3. Объедините новые коммиты в один коммит для каждой формулы:

   git rebase --interactive origin/HEAD

   Если вы работаете над PR для одной формулы, git commit --amend — удобный способ объединять коммиты по мере работы.

4. Отправьте изменения в ветку удалённого форка и обновите запрос на включение изменений:

   git push --force

После того как вы учтёте все замечания, если мы захотим включить изменения (а мы включаем большинство изменений), мы добавим их в Homebrew. Обратите внимание: из-за нашего способа объединения изменений статус PR может отображаться как «Closed» («Закрыт»), а не «Merged» («Включён»). Не беспокойтесь: ваше авторство будет указано в итоговом коммите.

Отлично, теперь вы участник проекта Homebrew!