Любой вклад приветствуется!¶
Мы приветствуем любой вклад в развитие технологии Hyperledger - задач всегда много!
Рекомендуем сперва ознакомится c Правилами поведения при работе с проектом Hyperledger. Важно поддерживать вежливую и дружескую атмосферу в сообществе.
Примечание
Если вы хотите дополнить или изменить эту документацию, ознакомьтесь с документом Style guide for contributors.
Как вы можете быть полезным¶
Есть много способов внесения собственного вклада в развитие Hyperledger Fabric, независимо от того, являетесь вы обычным пользователем или разработчиком.
Как пользователь, вы можете сделать свой вклад через:
- Предложение новых функций/улучшений
- Создание отчетов об ошибках
- Помощь в тестировании нового функционала согласно плану разработки. Свяжитесь с ответственным разработчиком через JIRA или RocketChat.
Как технический писатель или разработчик документации:
- Улучшайте существующие разделы документации и создавайте новые, используя свой опыт работы с Fabric. Доработка существующей документации — это простой способ внести свой вклад, облегчая другим пользователям понимание и работу с Fabric. Это также пополнит историю ваших изменений в проектах с открытым исходным кодом.
- Участвуйте в переводе документации на ваш родной язык, чтобы поддерживать актуальность документации Fabric на вашем языке. Документация Fabric уже доступна на большом количестве языков — английском, китайском, малаялам и бразильском португальском. Присоединяйтесь к команде и работайте над переводом последних обновлений документации! Вас ждет дружественное сообщество пользователей, писателей и разработчиков.
- Начните новый перевод, если документация Fabric недоступна на вашем языке. Команды китайского, малаялам и португальского бразильского начинали с нуля. Вы тоже сможете! Конечно, это большая работа. Вам придется сформировать сообщество писателей и организовать процесс внесения изменений. Но только представьте, что документация Fabric станет доступна на вашем родном языке.
Перейдите к разделу Внесение изменений в документацию, чтобы приступить к работе.
Как разработчик:
- Если у вас немного свободного времени, попробуйте поучаствовать в задачах типа «help-wanted». Более подробно смотрите Разрешение инцидентов и текущих задач.
- Если вы хотите посвятить больше времени — предложите новый функционал (см. раздел Предложение новых функций/улучшений) и соберите собственную команду для работы над ним, или присоединяйтесь к одной из существующих команд, работающих над текущими задачами. Найдите интересующую вас задачу в плане разработки и свяжитесь с ответственным за нее через JIRA или RocketChat.
Создание учетной записи Linux Foundation¶
Для участия в разработке проекта Hyperledger вам понадобится учетная запись Linux Foundation. После присвоения идентификатора Linux Foundation вы сможете получить доступ ко всем инструментам сообщества Hyperledger, в том числе: Управлению инциндентами Jira, RocketChat, а также Вики (только редактирование).
Следуйте инструкциям ниже для создания учетной записи Linux Foundation (если у вас ее еще нет).
- Перейдите на сайт Linux Foundation ID.
- Выберите опцию
I need to create a Linux Foundation ID
и заполните появившуюся форму. - Подождите несколько минут, затем проверьте указанный ящик электронной почты. Вы должны получить сообщение со следующей темой: «Validate your Linux Foundation ID email».
- Перейдите на URL-адрес, указанный в этом письме для подтверждения вашего адреса электронной почты.
- В окне браузере должно появиться сообщение
You have successfully validated your e-mail address
. - Перейдите к Управлению инциндентами Jira или зайдите в RocketChat.
Внесение изменений в документацию¶
Рекомендуем начать с внесения изменений в документацию. Эта быстрая и простая процедура познакомит вас с процессом, а также подтвердит, что все необходимые требования выполнены (установлено нужное программное обеспечение и т.д.). Чтобы начать, ознакомьтесь со следующими разделами:
Управление проектом¶
В Hyperledger Fabric используется открытая модель управления, описанная в уставе. Проекты и подпроекты управляются разработчиками. Для новых подпроектов выбирается изначальный набор разработчиков, которые одобряются существующими разработчиками проекта верхнего уровня при утверждении подпроекта.
Разработчики проекта¶
Проект Fabric управляется разработчиками проекта верхнего уровня. Разработчики несут ответственность за рассмотрение и включение в проект всех предлагаемых изменений. Также они руководят общим техническим направлением проекта в рамках руководящих принципов, установленных Техническим комитетом Hyperledger (TSC).
Как стать разработчиком проекта¶
Время от времени разработчики проекта рассматривают возможность добавления нового разработчика. Для этого кандидат:
- должен иметь хорошую историю проверок запросов на включение изменений (как качество, так и количество проверок);
- вносить новаторские идеи в проект;
- принимать участие в организации участников и проектной работы.
Существующий разработчик проекта может представить запрос на включение изменений в файл с перечнем разработчиков. Указанный участник может стать разработчиком при одобрении предложения большинством существующих разработчиков. После одобрения производится слияние набора изменений и участник добавляется в группу разработчиков.
Роль разработчика проекта снимается при собственном отказе, при длительном бездействии (например, 3 или более месяцев без проверок и комментариев), в случае нарушения правил поведения или при многократном вынесении неверных суждений. Предлагаемое удаление разработчика также требует одобрения большинства. Удаленный за бездействие разработчик проекта может быть восстановлен после возобновления стабильного участия и проверок (в течение месяца или более), демонстрируя прежнюю вовлеченность.
Каденция выпусков¶
Разработчики проекта Fabric установили ежеквартальную (приблизительно) каденцию выпусков (см. выпуски). В любой момент времени существует стабильная ветка выпуска LTS (с долгосрочной поддержкой), а также главная ветка для разработки новых функций. Присоединяйтесь к обсуждению в канале #fabric-release RocketChat.
Предложение новых функций/улучшений¶
Сперва, просмотрите JIRA на наличие схожих предложений (или недавно закрытых). Если вы не находите схожего предложения, рекомендуем открыть эпик или историю в JIRA, в зависимости от того, что из них лучше соответствует вашему предложению, а также указать ссылку или встроить одностраничное описание предложения, в котором указать назначение функции и как она может быть реализована. Также не будет лишним описать, в каких ситуациях может быть необходима или полезна предложенная функция в случае ее реализации. После создания карточки в JIRA и добавления описания в виде текста, вложения или ссылки на публично доступный документ, отправьте письмо с кратким описанием на электронный ящик списка рассылки fabric@lists.hyperledger.org с указанием карточки в JIRA и запросом обратной связи.
Обсуждение предлагаемой функции рекомендуется вести непосредственно в самой карточке JIRA для простоты отслеживания впоследствии.
Получение поддержки трех или более разработчиков Hyperledger Fabric касательно новой функции значительно повышает вероятность того, что связанные с функцией запросы с изменениями будут включены в последующий выпуск.
Совещания участников¶
Разработчики проектов регулярно проводят совещания участников. Целью совещаний участников является планирование и разбор прогресса выпусков и внесения изменений, а также обсуждение технического и функционального направления проекта и подпроектов.
Больше информации о совещаниях разработчиков приведено в соответствующем разделе вики.
Как описано выше, предложения по добавлению новых функций/улучшений должны быть представлены на совещании разработчиков для рассмотрения, получения обратной связи и принятия.
Общение¶
Разработчики используют RocketChat для общения и Google Hangouts™ для показа удаленного рабочего стола. Планирование и приоритезация разработки осуществляется с помощью JIRA. Более длительные обсуждения мы ведем с помощью списка рассылки.
Руководство по внесению изменений¶
Предварительные условия¶
Если вы еще этого не сделали, рекомендуем проверить всё ли необходимое программное обеспечение установлено на компьютерах, на которых будет вестись разработка блокчейн-приложений и/или которые будут поддерживать работу сети Hyperledger Fabric.
Получение помощи¶
Если вы ищете задачу, над которой можно поработать, или нужна помощь экспертов в нахождении или исправлении ошибок — наше сообщество всегда готово помочь. Для общения разработчиков предусмотрен чат, IRC (#hyperledger на freenode.net) или список рассылки. Мы не кусаемся :grin: и будем рады помочь. Единственный глупый вопрос — это тот, который вы стесняетесь задать. Вопросы на самом деле являются отличным способом улучшить проект, поскольку они подчеркивают места, в которых документация не совсем понятна.
Создание отчетов об ошибках¶
Если вы являетесь пользователем и нашли ошибку, создайте сообщение об ошибке в JIRA. Прежде чем создать новый карточку в JIRA, просмотрите существующие и убедитесь, что об это ошибке не сообщали ранее. Если об ошибке сообщали, можно добавить комментарий, указав, что вы также заинтересованы в исправлении ошибки.
Примечание
Если проблема связана с безопасностью, используйте процедуру сообщения об ошибках безопасности Hyperledger.
Если об этой ошибке ранее не сообщалось, можно создать запрос на включение изменений с подробным описанием ошибки и исправления.
Или создайте новую карточку в JIRA. В таком случае попробуйте предоставить подробное описание проблемы, чтобы кто-то другой смог попробовать ее воспроизвести.
Один из разработчиков проекта должен ответить на описание ошибки в течение 24 часов. Если никто не ответил, «поднимите» карточку с помощью комментария и запросите,
чтобы его рассмотрели. Также можно написать сообщение в соответствующий канал чата Hyperledger.
Например, об ошибке в документации следует написать в #fabric-documentation
, об ошибке в базах данных — #fabric-ledger
и т.д.
Отправка исправления¶
Если вы сообщили об обнаруженной ошибке в JIRA и хотите предоставить исправление, мы будем очень рады! Назначьте инцидент в JIRA на себя и затем отправьте запрос на включение изменений (PR). Подробное описание этой процедуры описано в документе GitHub Contributions.
Разрешение инцидентов и текущих задач¶
Просмотрите список инцидентов и выберите то, что вас интересует. Также просмотрите список «help-wanted». Рекомендуем начать с чего-то относительно простого и выполнимого, отдав предпочтение задачам, для решения которых никто еще не назначен. Если никто не назначен, назначьте карточку задачи на себя. Если не получается решить проблему в разумных пределах по времени, отмените назначение, или добавьте комментарий о том, что вы все еще активно работаете над решением, если вам нужно еще время.
Проверка представленных запросов на включение изменений¶
Еще один способ внести свой вклад и узнать больше о Hyperledger Fabric — это помочь разработчикам в проверке открытых запросов на включение изменений. Действительно, разработчикам зачастую непросто проверить все получаемые запросы на включение изменений и оценить необходимость их применения. Вы также можете просмотреть изменения кода и/или документации, протестировать их и сообщить разработчикам ваше мнение. Завершив проверку и/или тестирование, просто добавьте комментарии и/или проголосуйте в запросе на включение изменений. Такие комментарии, как «Я попробовал это на системе X и подтверждаю, что всё работает» или «Я получил ошибку на системе X: xxx» могут помочь разработчикам в процессе оценивания. В результате разработчики проекта смогут быстрее принять решение по поводу запроса на включение изменений, что ускорит весь процесс.
Для начала просмотрите открытые запросы на включение изменений в GitHub.
Устаревание запросов на включение изменений¶
Поскольку проект Fabric постоянно развивается, вместе с ним растет количество открытых запросов. Одной из проблем почти всех проектов является эффективное управление открытыми запросами, и проект Fabric не являются исключением. Чтобы контролировать рост количества открытых запросов проекта Fabric мы используем правила устаревания запросов, выполнение которых управляется ботами. Сходный процесс контроля количества открытых запросов существует в других крупных проектах.
Правила обработки устаревших запросов¶
Разработчики проекта Fabric отслеживают все действия с запросами на соответствие правилам. Если запрос на включение изменений не обновлялся в течение 2 недель, будет добавлено напоминание о том, что запрос необходимо обновить с указанием любых важных комментариев или же он будет отменен, если в изменениях более нет необходимости. Если такой запрос пробудет еще 2 недели без обновлений, он будет автоматически отменен. По прошествии 2 месяцев с момента создания запроса (вне зависимости от активности), он будет помечен, как требующий проверки разработчиком.
Если запрос прошел все проверки, но не был рассмотрен в течение 72 часов (3 суток), он будет ежедневно размещаться в канале #fabric-pr-review до тех пор, пока не получит комментарии о пройденной проверке.
Эти правила относятся ко всем официальным проектам Fabric (fabric, fabric-ca, fabric-samples, fabric-test, fabric-sdk-node, fabric-sdk-java, fabric-gateway-java, fabric-chaincode-node, fabric-chaincode-java, fabric-chaincode-evm, fabric-baseimage и fabric-amcl).
Настройка среды разработки¶
Далее попробуйте собрать проект в вашей среде разработки, чтобы убедиться в правильности всех настроек.
Пример хорошего запроса на включение изменений¶
- Одно изменение на один запрос. Не пять, не три, не десять. Одно и только одно. Почему? Потому, что это ограничивает область кода, на которую подействуют изменения. Гораздо проще определить источник проблем при наличии регрессии, чем в случае множества одновременных изменений, которые влияют на большой объем кода.
- Есть ссылка на измененяемую историю в JIRA. Почему? Во-первых, мы хотим отслеживать скорость разработки, чтобы более точно определять частоту выпуска новых версий. Во-вторых, так мы можем более эффективно находить обоснования изменениям. Во многих случаях предлагаемые изменения обсуждаются — мы хотим иметь возможность перейти к обсуждению из самого изменения.
- Включены модульные и интеграционные тесты (или изменения существующих тестов). Под тестами подразумевается не только проверка благоприятного сценария. Следует проводить также тестирование негативных сценариев любого кода, его способность правильно обрабатывать ошибки ввода. При написании кода вы несете ответственность за тестирование, а также предоставление тестов, демонстрирующих, что ваше изменение соответствует его описанию. Почему? Потому что без этого мы не узнаем, работает ли на самом деле наша текущая кодовая база.
- Модульные тесты не должны иметь внешних зависимостей. Для запуска модульных тестов должно быть достаточно выполнения команды
go test
или эквивалентной на другом языке. Любой тест, у которого есть внешние зависимости (например, требующий запуск другого компонента), должен иметь их имитацию. Иначе это не модульное, а уже интеграционное тестирование. Почему? Потому, что многие разработчики, работающие с открытым исходным кодом, используют процесс разработки через тестирование. Они испльзуют инструменты, которые автоматически вызывают тесты при изменении кода. Это гораздо более эффективно в сравнении с осуществлением полной сборки для каждого изменения кода. В этом определении модульного тестирования приводится хороший набор критериев, о которых следует помнить при написании эффективных модульных тестов. - Минимально возможное количество строк кода. Почему? Не забывайте, что у разработчиков проекта есть обычная работа. Как вы думаете, сколько времени потребуется на проверку запроса с 1000 или 2000 строками кода? Рекомендуем, чтобы объем изменений не превышал 200–300 строк кода. Если этого объема недостаточно, разбейте изменение на несколько отдельных изменений. При добавлении нескольких новых функций для поддержки новых возможностей, добавляйте функции отдельно с соответствующими тестами, а затем напишите код, который использует функции для обеспечения новых возможностей. Конечно, всегда есть исключения. При добавлении небольшого изменения и 300 строчек тестов, конечно же мы простим вас ;-) Особенно, если изменение влияет на большой объем кода или содержит большое количество сгенерированного кода (данные в формате protobuf и подобное). Опять же, могут быть исключения.
Примечание
Запросы на включение изменений более 300 строк скорее всего не получат одобрение и вас попросят изменить код для соответствия требованиям этого руководства.
- Понятное и содержательное описание изменений. Укажите информативный заголовок длиной не более 55 символов, вставьте пустую строку, а затем приведите более полное описание изменений. Каждое изменение должно включать идентификатор JIRA, соответствующий изменению, например, [FAB-1234]. Идентификатор можно указать в названии, но также следует указать в теле описания изменения.
Примечание
Пример описания изменений:
Исправление [FAB-1234] для foobar()
В исправлении [FAB-1234] добавлена проверка того, что при вызове foobar(foo string) строка аргумента не является нулевой.
Наконец, будьте отзывчивыми. Не допускайте, чтобы запрос оставался с неотвеченными комментариями проверяющих, что в итоге потребует использования команды rebase. Это создаст дополнительную отсрочку и добавит вам работы при исправлении конфликтов слияния.
Правовые вопросы¶
Примечание. Каждый исходный файл должен включать в себя заголовок c лицензией программного обеспечения Apache 2.0. По следующей ссылке приведен шаблон заголовка лицензии.
Мы попытались сделать его максимально простым для процедуры внесения изменений. В заголовке указывается, каким образом учитываются правовые аспекты внесения изменений. Мы используем Сертификаты разработчика 1.1 (DCO) — подход, который используется сообществом Linux® Kernel для управлениями изменениями в коде.
Мы просим, чтобы при отправке патча на рассмотрение разработчик включал подпись в описании изменения.
Ниже приведен пример подписи, которая подтверждает, что отправитель принимает правила DCO:
Signed-off-by: John Doe <john.doe@example.com>
Можно включить автоматическую подпись при отправке изменений из локального репозитория GIT, используя команду git commit -s
.