Отправка запроса на слияние

Если вы хотите внести вклад в репозиторий ESLint, отправьте запрос на слияние через GitHub. Это самый быстрый способ проверить ваш код и добавить его в кодовую базу. Не создавайте issue с фрагментами кода. В этом случае нам придётся вручную вносить изменения и обновлять соответствующие тесты. Из-за этого вероятность того, что ваш код будет включён своевременно, снижается. Используйте запросы на слияние.

Начало работы

Проект ESLint использует issues для отслеживания задач, поэтому важно убедиться, что для вашей задачи создана подходящая issue:

• Если issue уже существует, следуйте инструкциям в разделе работа над issues.
• Если подходящей issue нет, создайте её и опишите планируемые изменения. Используйте подходящий шаблон issue.
  • Исключения: для небольших изменений, таких как исправления ошибок, обновления документации или обновления пакетов, issue не требуется. Убедитесь, что в описании запроса на слияние чётко объясняется, что вы делаете и зачем.

После этого можно приступать к работе над кодом.

Работа с кодом

Процесс отправки запроса на слияние довольно прост и обычно каждый раз проходит по одной и той же схеме:

1. Создайте новую ветку.
2. Внесите изменения.
3. Перебазируйтесь на upstream.
4. Запустите тесты.
5. Проверьте отправляемые изменения.
6. Отправьте изменения.
7. Отправьте запрос на слияние.

Подробное описание каждого шага приведено ниже.

Шаг 1. Создайте новую ветку

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

git checkout -b issue1234

Всю работу над задачей следует выполнять в этой ветке.

Примечание: Не объединяйте исправления для нескольких задач в одной ветке. Создавайте отдельную ветку для каждой задачи, над которой работаете.

Шаг 2. Внесите изменения

Вносите изменения в код и тесты, следуя по ходу работы соглашениям о написании кода. Завершив работу, зафиксируйте изменения в своей ветке:

git add -A
git commit

Во всех проектах ESLint для сообщений коммитов используются Conventional Commits. (Примечание: необязательную область действия в сообщениях мы не поддерживаем.) Пример сообщения коммита:

tag: Short description of what you did

Longer description here if necessary

Fixes #1234

Первая строка сообщения коммита (краткое описание) должна иметь определённый формат. Этот формат проверяется нашими инструментами сборки. Хотя само сообщение коммита не проверяется напрямую, оно используется для создания заголовка запроса на слияние, который проверяется при отправке запроса.

tag — одно из следующих значений:

• fix — исправление ошибки.
• feat — обратно совместимое улучшение или изменение правила, которое приводит к появлению новых сообщений о проблемах.
• fix! — обратно несовместимое исправление ошибки.
• feat! — обратно несовместимое улучшение или новая возможность.
• docs — изменения только в документации.
• chore — изменения, не заметные пользователям.
• build — изменения только в процессе сборки.
• refactor — изменения, не влияющие на API или взаимодействие с пользователем.
• test — изменения только в файлах тестов.
• ci — изменения в файлах конфигурации и скриптах CI.
• perf — изменение кода, повышающее производительность.

Чтобы определить подходящий тег, используйте метки issue, над которой вы работаете.

Краткое описание в сообщении должно состоять из одного предложения, описывающего изменения, и содержать не более 72 символов. Если запрос на слияние решает issue, укажите её номер в теле сообщения коммита в формате Fixes #1234. Если коммит не решает issue полностью, используйте Refs #1234 вместо Fixes #1234.

Вот несколько примеров удачных кратких описаний коммитов:

build: Update Travis to only test Node 0.10
fix: Semi rule incorrectly flagging extra semicolon
chore: Upgrade Esprima to 1.2, switch to using comment attachment

Шаг 3. Перебазируйтесь на upstream

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

git fetch upstream
git rebase upstream/main

Шаг 4. Запустите тесты

После перебазирования обязательно запустите все тесты ещё раз, чтобы убедиться, что ничего не сломалось:

npm test

Если какие-либо тесты завершатся с ошибкой, исправляйте код, пока все тесты не будут пройдены.

Шаг 5. Проверьте отправляемые изменения

Когда код готов, самое время ещё раз проверить отправляемые изменения и убедиться, что они соответствуют нашим соглашениям. Проверьте следующее:

• Сообщение коммита оформлено правильно.
• Изменения не приводят к функциональным регрессиям. Перед отправкой запроса на слияние обязательно запустите npm test, чтобы проверить изменения.
• Для несвязанных изменений создавайте отдельные запросы на слияние. Большие запросы с несколькими несвязанными изменениями могут быть закрыты без слияния.
• Все изменения должны сопровождаться тестами, даже если ранее для добавляемой функции тестов не было.
• Все изменения, заметные пользователям, должны сопровождаться соответствующей документацией.
• Следуйте соглашениям о написании кода.

Шаг 6. Отправьте изменения

Затем отправьте изменения в свой клон репозитория:

git push origin issue1234

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

git push -f origin issue1234

Шаг 7. Отправьте запрос на слияние

Теперь можно отправить запрос на слияние. Перейдите в свой форк ESLint и следуйте документации GitHub о том, как отправить запрос на слияние.

Чтобы отправить код или документацию в проект ESLint, при отправке первого запроса на слияние вам будет предложено подписать наше CLA. (Подробнее о процессе подписания CLA в OpenJS Foundation можно узнать на странице https://cla.openjsf.org/.)

Заголовок запроса на слияние автоматически создаётся из краткого описания первого коммита, но его можно изменить перед отправкой запроса.

В описании запроса на слияние следует объяснить, что вы сделали и как можно увидеть результат.

При слиянии запроса все его коммиты будут объединены в один. Первая строка сообщения объединённого коммита будет содержать заголовок запроса на слияние и его номер. Формат заголовка важен, поскольку заголовки используются для создания списка изменений для каждого выпуска. Тег и номер issue помогают создавать более единообразные и полезные списки изменений.

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

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

1. Следить за статусом сборки CI в GitHub Actions для вашего запроса на слияние. Если сборка завершится с ошибкой, выясните причину. Мы не можем объединять запросы на слияние, если сборка CI завершилась с ошибкой по любой причине.
2. Отвечать на комментарии участников команды к запросу на слияние. Помните: мы хотим помочь вам включить ваш код, поэтому отнеситесь внимательно к нашим отзывам.
3. Быть готовыми к тому, что мы попросим вас внести изменения, выполнить перебазирование или объединить коммиты.

Изменение заголовка запроса на слияние

Если заголовок запроса на слияние оформлен неправильно, вас попросят его изменить. Это можно сделать через интерфейс GitHub.

Обновление кода

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

git add -A
git commit
git push origin issue1234

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

Сообщения последующих коммитов не должны иметь какой-либо определённый формат, поскольку эти коммиты не попадают в список изменений.

Перебазирование

Если ваш код устарел, мы можем попросить вас выполнить перебазирование. Это значит, что мы хотим применить ваши изменения поверх последней версии кода из upstream. Настройте среду разработки, а затем выполните перебазирование с помощью следующих команд:

git fetch upstream
git rebase upstream/main

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

git push origin issue1234 -f