Руководство по внесению вклада

Процесс отправки патчей

Следующие рекомендации по процессу отправки помогут вам быть более эффективными при отправке кода в проект JerryScript.

Когда разработка завершена, набор патчей должен быть отправлен через запросы на вытягивание (pull requests) на GitHub. Будет проведён обзор набора патчей. После принятия набор патчей будет интегрирован в основную ветку, проверен и протестирован. Затем разработчик-автор несёт ответственность за поддержку кода на протяжении всего его жизненного цикла.

Пожалуйста, отправляйте все патчи публично, открывая запрос на вытягивание. Патчи, отправленные частным образом сопровождающим и коммиттерам, не будут рассматриваться. Поскольку проект JerryScript является проектом с открытым исходным кодом, будьте готовы к обратной связи и критике — это случается со всеми. Если вас попросят переработать код, проявите настойчивость и отправьте повторно после внесения изменений.

1. Ограничьте объём патча

Небольшие патчи, как правило, легче понять и протестировать, поэтому, пожалуйста, вносите изменения как можно меньшими порциями, насколько это возможно. Меньшие патчи с меньшей вероятностью будут иметь непредвиденные последствия, а если они возникнут, то добраться до первопричины будет намного проще для вас и сопровождающих и коммиттеров. Кроме того, небольшие патчи гораздо чаще принимаются.

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

Любой код, который вы хотите внести в проект, должен быть лицензирован под Apache License 2.0. Вклады под другой лицензией не могут быть приняты. Каждый файл должен начинаться со следующего заголовка:

/* Copyright JS Foundation and other contributors, http://js.foundation
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

Добавление уведомлений об авторских правах, отличных от уведомления о проекте («Copyright JS Foundation и другие участники, http://js.foundation»), не допускается. Единственным исключением является добавление стороннего кода, для которого необходимо сохранить уведомления об авторских правах. Добавление стороннего кода в проект обычно требует веского обоснования.

3. Подпишите свою работу сертификатом происхождения разработчика JerryScript

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

У нас те же требования к использованию процесса подписания, что и у ядра Linux. Короче говоря, вам нужно включить тег signed-off-by в каждый патч.

Вы должны использовать своё настоящее имя и адрес электронной почты в следующем формате:

JerryScript-DCO-1.0-Signed-off-by: Random J Developer random@developer.example.org

«JerryScript-DCO-1.0-Signed-off-by» — это сертификат разработчика о том, что он или она имеет право представить патч для включения в проект. Это соглашение с сертификатом происхождения JerryScript Developer's Certificate of Origin. Код без надлежащего подписания не может быть объединён с основной линией.

4. Откройте запрос на вытягивание GitHub

Инструкции по открытию запроса на вытягивание можно найти здесь.

5. Что делать, если мой патч отклонён?

Это происходит постоянно по многим причинам, и не обязательно потому, что код плохой. Примите обратную связь, адаптируйте свой код и попробуйте ещё раз. Помните, конечная цель — сохранить качество кода и поддерживать фокус проекта посредством интенсивного анализа.

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

Если у вас есть веская техническая причина не согласиться с отзывом, и вы считаете, что эта причина была проигнорирована, потратьте время на то, чтобы подробно объяснить её в своём ответе.

6. Code review

Code review может быть выполнен всеми участниками проекта (не только сопровождающими и коммиттерами). Участники могут просматривать изменения кода и делиться своим мнением с помощью комментариев, руководствуясь следующими принципами:

• Обсуждайте код; никогда не обсуждайте автора кода.
• Уважайте и признавайте вклад, предложения и комментарии.
• Слушайте и будьте открыты для всех разных мнений.
• Помогайте друг другу.

Изменения отправляются через запросы на вытягивание (pull requests), и только сопровождающие и коммиттеры должны одобрить или отклонить запрос на вытягивание (обратите внимание, что только сопровождающие могут давать обязательные оценки обзора).

Изменения следует рассматривать в разумные сроки. Сопровождающие и коммиттеры должны оставлять изменения открытыми в течение некоторого времени (как минимум один полный рабочий день), чтобы другие могли высказать своё мнение. Время рассмотрения увеличивается со сложностью проверки.

Советы по запросам на вытягивание на GitHub

• Форкните репозиторий GitHub и клонируйте его локально.
• Подключите свой локальный репозиторий к исходному вышестоящему репозиторию, добавив его в качестве удалённого.
• Создайте ветку для своих правок.
• Часто загружайте изменения из вышестоящего репозитория, чтобы оставаться в курсе событий, так что когда вы отправите свой запрос на вытягивание, вероятность конфликтов слияния будет меньше.

Для получения более подробной информации см. рекомендации GitHub по синхронизации форка.

Как автоматически добавлять строку DCO в каждый коммит

Легко забыть добавить строку DCO в конец каждого сообщения о коммите. К счастью, есть хороший способ сделать это автоматически. После того как вы клонировали репозиторий на свой компьютер, вы можете добавить хук prepare commit message в каталог .git/hooks, например, таким образом:

#!/usr/bin/env python

import sys

commit_msg_filepath = sys.argv[1]

with open(commit_msg_filepath, "r+") as f:
    content = f.read()
    f.seek(0, 0)
    if "Signed-off-by" not in content:
        f.write("\n\nJerryScript-DCO-1.0-Signed-off-by: <Ваше имя> <Ваш email>\n%s" % content)
    else:
        f.write(content)

Дополнительную информацию см. в разделе «Git Hooks» книги Git.