Предложить изменения (Pull Request)

Если вы хотите внести вклад в репозиторий ESLint, пожалуйста, используйте запрос на изменение (pull request) на GitHub. Это самый быстрый способ для нас оценить ваш код и объединить его в базу кода. Пожалуйста, не создавайте issue с фрагментами кода. В этом случае нам придётся вручную объединять изменения и обновлять соответствующие тесты. Это снижает вероятность того, что ваш код будет включён в своевременном порядке. Пожалуйста, используйте pull request.

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

Если вы хотите работать над pull request и никогда раньше не отправляли код, следуйте этим шагам:

1. Настройте среду разработки.
2. Если вы хотите внести изменение, которое повлияет на стабильность кода, или внести изменения в ядро, убедитесь, что существует issue, описывающий ваши действия, и что этот issue принят. Вы можете создать новый issue или просто указать, что вы работаете над существующим issue. Исправления ошибок, изменения документации и другие pull requests не требуют issue.

После этого вы готовы начать работу с кодом.

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

Процесс отправки pull request достаточно простой и обычно следует одному и тому же шаблону:

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

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

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

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

git checkout -b issue1234

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

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

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

Внесите изменения в код и тесты, следуя конвенциям кодирования. После завершения зафиксируйте изменения в вашей ветке:

git add -A
git commit

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

tag: Short description of what you did

Longer description here if necessary

Fixes #1234

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

tag является одним из следующих:

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

Используйте метки issue, над которым вы работаете, чтобы определить лучший тег.

Резюме сообщения должно содержать однопредложное описание изменения и иметь длину 72 символа или меньше. Если pull request обрабатывает issue, то номер 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

Перед отправкой pull request убедитесь, что вы сделали ребейз на исходный код upstream. Это гарантирует, что ваш код работает с последней доступной версией кода.

git fetch upstream
git rebase upstream/main

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

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

npm test

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

Шаг 5: Проверьте отправку

Когда ваш код готов, это хорошее время, чтобы дважды проверить отправку, убедившись, что она соответствует нашим соглашениям. Вот что нужно проверить:

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

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

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

git push origin issue1234

Если вы не можете отправить, потому что некоторые ссылки устарели, сделайте принудительную отправку:

git push -f origin issue1234

Шаг 7: Отправьте pull request

Теперь вы готовы отправить pull request. Перейдите к вашему форку ESLint, а затем следуйте документации GitHub о том, как отправить pull request.

Для отправки кода или документации в проект ESLint от вас потребуется подписать наше CLA при отправке первого pull request. (Подробнее о процессе CLA OpenJS Foundation см. https://cla.openjsf.org/.)

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

Описание pull request должно объяснять, что вы сделали и как можно увидеть его последствия.

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

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

После отправки вашего pull request пришло время команде его проверить. Поэтому, пожалуйста, убедитесь в следующем:

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

Обновление заголовка pull request

Если заголовок вашего pull request имеет неправильный формат, вам будет предложено его обновить. Вы можете сделать это через интерфейс GitHub.

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

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

git add -A
git commit
git push origin issue1234

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

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

Rebasing

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

git fetch upstream
git rebase upstream/main

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

git push origin issue1234 -f