Вклад в Eclipse OMR

Спасибо за ваш интерес к этому проекту.

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

Если вы новичок в работе с git, вы можете использовать наш Git Crash Course, чтобы помочь вам начать работу.

Проблемы

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

Посетите нашу страницу проблем на GitHub для поиска и отправки.

Маркировка

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

Часть меток задокументирована ниже.

• good first issue обычно относится к задаче, которая подойдёт для кого-то нового в проекте с небольшим опытом работы с технологией или даже с проектами и процессами с открытым исходным кодом. Они предназначены для всех, кто хочет мягко окунуться в создание, тестирование или ознакомление с частью кодовой базы.

• Проблемы с меткой bug — это функциональные проблемы, ошибки или неожиданное поведение.

• Метки build/configure используются для описания проблем со сборкой и системой настройки (например, make-файлы, autotools configure).

• Метка ci используется для проблем и улучшений с системой непрерывной интеграции для тестирования запросов на вытягивание (например, Jenkins, Azure и т. д.).

• Метки cmake похожи на build/configure, но они применяются конкретно к конфигурации CMake.

• Метка compiler arch review используется, чтобы указать, что проверка этой проблемы или запроса на вытягивание на встрече по архитектуре компилятора OMR запрашивается перед фиксацией.

• Метка documentation используется для проблем или улучшений документации (либо в самом исходном коде, либо в отдельных файлах документации).

• Проблемы с пометкой epic используются для группировки связанных проблем и для отслеживания более крупных целей в проекте через проблемы.

• Метка GSoC Project предназначена для потенциальных идей для проектов Google Summer Of Code.

• Проблемы с отметкой help wanted имеют ценность для проекта, но нет немедленных человеческих ресурсов для их выполнения. Те, кто ищет задачу, которую можно выполнить самостоятельно. Кто-то ещё не работает над этим, но можно рассмотреть следующие варианты.

• license — используются для обозначения проблем, связанных с лицензией исходного кода.

• meeting — используются для обозначения вопросов, касающихся повесток дня или протоколов совещаний проекта.

• toolchain bug — используются для документирования проблем или запросов на вытягивание, которые описывают или реализуют обходной путь для ошибки в цепочке инструментов разработки (например, компиляторе), используемой для создания OMR. Обходные пути цепочки инструментов должны быть временными по своей природе, и цель этой метки состоит в том, чтобы сделать такие обходные пути легко обнаруживаемыми в будущем, чтобы они не потерялись в коде.

• tooling — предназначены для решения проблем, связанных со вспомогательными инструментами, необходимыми для поддержки любого кода или процессов в рамках проекта.

Метки также используются для классификации проблем и запросов на вытягивание по основному технологическому компоненту Eclipse OMR, который они затрагивают. Например:

Дальнейшая классификация по архитектуре процессора, операционной системе и разрядности может быть достигнута с помощью следующих меток:

• arch:aarch32

• arch:aarch64

• arch:power

• arch:riscv

• arch:x86

• arch:z

• os:aix

• os:linux

• os:macos

• os:windows

• os:zos

• bits:32

• bits:64

Отправка вклада

Вы можете предложить свой вклад, отправив запросы на вытягивание через GitHub. Следование этим рекомендациям поможет нам без проблем объединить ваши запросы на вытягивание:

1. Eclipse OMR — это проект Фонда Eclipse. Все участники должны подписать Соглашение участника Eclipse (или ECA) в соответствии с инструкциями на этой странице, прежде чем будет принят какой-либо вклад.

См. Юридические соображения Eclipse OMR для дополнительных соображений ECA при создании коммитов проекта, а также требований к авторским правам и лицензированию файлов. 2. Если вы не уверены, что ваш вклад будет принят, и хотите проверить свой подход или идею перед написанием кода, не стесняйтесь открыть вопрос. Однако не для каждой функции или исправления требуется вопрос. Если проблема и исправление чётко связаны между собой, и у вас есть готовое решение, смело отправляйте пул-реквест.

3. Ваш пул-реквест — это возможность объяснить, какие изменения вы хотели бы внести, а также почему вы хотите их добавить. Предоставление ясности о том, почему вы хотите изменений, облегчает принятие и предоставляет ценный контекст для рассмотрения.

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

5. Используйте только те возможности языка C++, которые поддерживаются нашими компиляторами. Список поддерживаемых возможностей можно найти здесь.

6. Следуйте рекомендациям по коммитам, описанным ниже.

7. Мы рекомендуем вам открывать пул-реквесты как можно раньше и отмечать их как «Работа в процессе» (добавляйте префикс WIP к названию PR). Это позволяет начать получать обратную связь на раннем этапе и помогает создать более качественный конечный продукт. Коммиттеры будут ждать, пока вы не удалите префикс WIP, чтобы объединить ваши изменения.

8. Если вы вносите изменение в технологию компилятора, которое включает модификации промежуточного языка Testarossa (IL) (включая, но не ограничиваясь добавлением нового IL-кода операции, изменением свойств кода операции или добавлением нового типа данных) или, по мнению коммиттера, фундаментального элемента инфраструктуры компилятора, коммиттер запросит, чтобы этот пул-реквест был представлен на предстоящем собрании по архитектуре компилятора OMR, чтобы инициировать обсуждение сообщества перед объединением. Вопросы такого же характера также могут быть предложены для обсуждения перед тем же собранием по архитектуре до создания пул-реквеста.

Зависимости от последующих проектов

Если последующий проект, использующий OMR, зависит от содержимого вашего пул-реквеста, то есть пул-реквест не должен объединяться до тех пор, пока все последующие приготовления не будут завершены, вы как автор пул-реквеста можете использовать префикс WIP в дополнение к комментарию в указанном пул-реквесте, чтобы сообщить коммиттеру о ваших конкретных обстоятельствах для объединения. То есть вы можете запросить проверку пул-реквеста, даже если он помечен как WIP, сообщая коммиттеру о вашем желании координировать, когда PR будет объединён. Как только все последующие приготовления будут завершены, вы, как автор, должны удалить префикс WIP и сообщить коммиттерам, что пул-реквест готов к объединению после завершения проверок.

Рекомендации по коммитам

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

Тело должно быть перенесено на 72 символа, где это разумно.

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

Пожалуйста, добавьте [skip ci] в сообщение коммита, когда изменение не требует компиляции, например, изменения только в документации, чтобы избежать ненужной траты ресурсов сборки проекта.

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

В строках нижнего колонтитула используется форма:

Ключ: Значение

Когда коммит связан с проблемами или другими коммитами, объясните эту связь в теле сообщения.

Также следует оставить тег Issue в нижнем колонтитуле. Однако если это финальный коммит, который решает проблему, вместо этого следует оставить тег Closes (или один из тегов, описанных здесь) в нижнем колонтитуле, чтобы автоматически закрыть указанную проблему при слиянии запроса на вытягивание.

Например, если это только один из коммитов, необходимых для решения проблемы №1234, то следующее сообщение является допустимым:

Исправить гонку в frobnicator

Этот патч устраняет состояние гонки в проблеме №1234.

Проблема: #1234

Однако, если это окончательный коммит, решающий проблему, то допустимо следующее сообщение:

Исправить гонку в frobnicator

Этот патч устраняет состояние гонки в проблеме №1234.

Закрывает: #1234

Авторство коммита

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

Если у коммита несколько авторов, все они должны быть указаны в строке Co-authored-by: Полное имя <адрес электронной почты> в нижнем колонтитуле каждого коммита. Каждый соавтор должен подписать Соглашение о внесении вклада ECA.

Каждый раз, когда коммит отправляется, автоматически запускается проверка GitHub CI, которая проверяет, что автор(ы) коммита подписал Соглашение о внесении вклада в Eclipse. В противном случае проверка не пройдёт, и результат будет виден в запросе на вытягивание.

Пример коммитов

Вот пример хорошего коммита:

Обновить и расширить руководство по коммитам

Уточните правила оформления сообщений о коммитах. Эти новые правила оформления основаны на обсуждении, найденном в #124.

Правила оформления изменены следующим образом:
- Предоставить рекомендации по написанию хорошей первой строки.
- Уточнить требования к оформлению.
- Ослабить рекомендацию использовать проблемы для нетривиальных коммитов.
- Перенести ссылки на проблемы из первой строки в нижний колонтитул сообщения.
- Поощрять участников добавлять больше информации в сообщение о коммите.

Проблема: #124

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

Следующий пример — плохой коммит:

FIX #124: Изменение пары случайных вещей в CONTRIBUTING.md. Также есть некоторые исправления ошибок в библиотеке потоков.

Коммит объединяет несвязанные изменения вместе очень плохим образом. Информации недостаточно, чтобы сообщение о коммите было полезным. Первая строка не имеет смысла или не является императивом. Сообщение оформлено неправильно, а проблема указана неправильно.

Другие ресурсы для написания хороших коммитов

— http://chris.beams.io/posts/git-commit/.

Установите скрипт перехвата сообщений git для проверки локальных коммитов

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

cd omr_repo_dir
cp scripts/commit-msg .git/hooks
chmod +x .git/hooks/commit-msg

Если хук отклоняет ваш коммит, сообщение останется в omr_repo_dir/.git/COMMIT_EDITMSG.

Не забывайте время от времени обновлять версию скрипта, так как он может развиваться по мере развития наших правил оформления коммитов.

Юридические аспекты Eclipse OMR

Запросы на вытягивание

Когда создаётся запрос на вытягивание (или когда новые коммиты отправляются в существующий запрос), веб-сервис автоматически запускает проверку, которая подтверждает, что адрес электронной почты каждого автора коммита совпадает с адресом электронной почты, подписавшим Соглашение о внесении вклада ECA. Эта служба чувствительна к регистру, поэтому регистр адресов электронной почты должен точно совпадать. Успех или неудача этой веб-службы будет сообщён в запросе на вытягивание GitHub. Запросы на вытягивание с неудачной проверкой ECA не будут объединены.

Запросы на вытягивание Eclipse OMR не обязательно должны быть подписаны, но большинство участников делают это в качестве наилучшей практики.

Уведомление об авторских правах и требования лицензирования

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

OMR имеет двойную лицензию в соответствии с Eclipse Public License 2.0 и Apache License v2.0. Любая ранее нелицензионная работа должна быть выпущена под той же лицензией.

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

Шаблон уведомления об авторских правах и двойной лицензии выглядит следующим образом:

/*******************************************************************************
 *  Copyright ${author} and others 2017
 *
 *  Этот программа и сопутствующие материалы доступны на условиях Eclipse Public License 2.0, которая сопровождает это распространение и доступна по адресу https://www.eclipse.org/legal/epl-2.0/ или Apache License, Version 2.0, которая также доступна по адресу https://www.apache.org/licenses/LICENSE-2.0.
 *
 * Этот исходный код также может быть доступен по следующим вторичным лицензиям, когда выполняются условия доступности, изложенные в Eclipse Public License, v. 2.0: GNU General Public License, версия 2 с исключением GNU Classpath [1] и GNU General Public License, версия 2 с OpenJDK Assembly Exception [2].
 *
 * [1] https://www.gnu.org/software/classpath/license.html
 * [2] https://openjdk.org/legal/assembly-exception.html
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 OR GPL-2.0-only WITH OpenJDK-assembly-exception-1.0
 *******************************************************************************/