Предложение. Вы можете оставить эту идею нам или кому-то другому для разработки, либо реализовать её самостоятельно.

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

1. Назначьте созданную вами задачу себе перед тем, как начать работать над ней.
2. Работайте над предложенной функцией и следуйте нашим руководящим принципам для кода и документации.
3. Когда будете готовы открыть запрос на включение изменений (pull request), убедитесь, что вы следуете этикету запроса на включение изменений и пометьте его как реализующий ранее созданную задачу:

feat: Описание функции

Объяснение функции

Закрывает #1234

4. Если ваше изменение требует изменения API, используйте тег api-changes.

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

Задавать вопросы

Вопрос — это любое обсуждение, которое не является ошибкой, запросом на функцию или оптимизацию.

Ваш первый вклад в код

1. Найдите простую задачу среди задач с меткой good-first-issue.
2. Убедитесь, что никто другой не работает над выбранными задачами, проверив, что они никому не назначены.
3. Назначьте задачу себе, чтобы другие могли видеть, что кто-то над ней работает.
4. Прочитайте наш Rust Style Guide перед началом написания кода.
5. Когда будете готовы зафиксировать свои изменения, прочитайте этикет запроса на включение изменений.

Этикет запроса на включение изменений

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

Работа над вкладом в код:

— Следуйте Rust Style Guide и Руководству по стилю документации. — Убедитесь, что написанный вами код покрыт тестами. Если вы исправили ошибку, превратите минимальный рабочий пример, который воспроизводит ошибку, в тест.

Фиксация вашей работы:

— Следуйте Git Style Guide. — Сжимайте ваши фиксации либо до, либо во время слияния. — Если во время подготовки вашего запроса на включение изменений ваша ветка устарела, перебазируйте её локально с помощью git pull --rebase upstream main. В качестве альтернативы вы можете использовать раскрывающееся меню для кнопки «Обновить ветку» и выбрать опцию «Обновление с перебазированием».

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

Создание запроса на включение изменений:

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

Объединение вашей работы:

— Запрос на включение изменений должен пройти все автоматические проверки перед объединением. Как минимум, код должен быть отформатирован, проходить все тесты и не иметь активных предупреждений clippy. — Запрос на включение изменений не может быть... В соответствующих коммитах, отдельно от остальной работы:

• Добавляйте тесты для функциональности в тот же коммит, что и эта функциональность.

Тесты и бенчмарки

— Для запуска тестов на основе исходного кода выполните команду cargo test в корне Iroha. Обратите внимание, что это длительный процесс.

— Чтобы запустить бенчмарки, выполните команду cargo bench из корня Iroha. Чтобы помочь в отладке выходных данных бенчмарков, установите переменную среды debug_assertions следующим образом: RUSTFLAGS="--cfg debug_assertions" cargo bench.

— Если вы работаете над определённым компонентом, помните, что при выполнении команды cargo test в рабочей области будут выполняться только тесты для этой рабочей области, которые обычно не включают интеграционные тесты.

— Если вы хотите протестировать свои изменения в минимальной сети, предоставленный файл docker-compose.yml создаёт сеть из 4 пиров Iroha в контейнерах Docker, которую можно использовать для тестирования логики консенсуса и распространения активов. Мы рекомендуем взаимодействовать с этой сетью либо с помощью iroha-python, либо с включённым клиентским CLI Iroha.

— Не удаляйте неудачные тесты. Даже игнорируемые тесты в конечном итоге будут запущены в нашем конвейере.

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

Отладка тестов

Если один из ваших тестов не проходит, вы можете захотеть уменьшить максимальный уровень ведения журнала. По умолчанию Iroha регистрирует только сообщения уровня INFO, но сохраняет возможность создавать журналы уровней DEBUG и TRACE. Этот параметр можно изменить либо с помощью переменной среды LOG_LEVEL для основанных на коде тестов, либо с помощью конечной точки /configuration на одном из пиров в развёрнутой сети.

Хотя журналов, напечатанных в stdout, достаточно, вам может показаться более удобным создавать журналы в формате json в отдельный файл и анализировать их с помощью node-bunyan или rust-bunyan.

Установите переменную среды LOG_FILE_PATH в соответствующее место для хранения журналов и проанализируйте их с помощью указанных пакетов.

Отладка с использованием консоли tokio

Иногда для отладки может быть полезно проанализировать задачи tokio с помощью tokio-console.

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

RUSTFLAGS="--cfg tokio_unstable" cargo build --features tokio-console

Порт для консоли tokio можно настроить через параметр конфигурации LOG_TOKIO_CONSOLE_ADDR (или переменную окружения). Использование консоли tokio требует, чтобы уровень журнала был TRACE, его можно включить через параметр конфигурации или переменную среды LOG_LEVEL.

Пример запуска Iroha с консолью tokio с использованием scripts/test_env.sh:

# 1. Скомпилируйте Iroha
RUSTFLAGS="--cfg tokio_unstable" cargo build --features tokio-console
# 2. Запустите Iroha с уровнем журнала TRACE
LOG_LEVEL=TRACE ./scripts/test_env.sh setup
# 3. Получите доступ к Iroha. Пиры будут доступны на портах 5555, 5556, ...
tokio-console http://127.0.0.1:5555

Профилирование

Чтобы оптимизировать производительность, полезно профилировать Iroha.

Для этого вы должны скомпилировать Iroha с профилем profiling и с функцией profiling:

RUSTFLAGS="-C force-frame-pointers=on" cargo +nightly -Z build-std build --target your-desired-target --profile profiling --features profiling

Затем запустите Iroha и подключите профилировщик по вашему выбору к идентификатору процесса Iroha (PID).

Также можно собрать Iroha... Внутри Docker с поддержкой профилировщика и профиль Iroha таким образом.

docker build -f Dockerfile.glibc --build-arg="PROFILE=profiling" --build-arg='RUSTFLAGS=-C force-frame-pointers=on' --build-arg='FEATURES=profiling' --build-arg='CARGOFLAGS=-Z build-std' -t iroha:profiling .

Например, используя perf (доступно только на Linux):

# для захвата профиля
sudo perf record -g -p <PID>
# для анализа профиля
sudo perf report

Чтобы иметь возможность наблюдать за профилем исполнителя во время профилирования Iroha, исполнитель должен быть скомпилирован без удаления символов. Это можно сделать, выполнив:

# скомпилировать исполнитель без оптимизаций
cargo run --bin iroha_wasm_builder -- build ./path/to/executor --out-file executor.wasm

С включённой функцией профилирования Iroha предоставляет конечную точку для очистки профилей pprof:

# профилировать Iroha в течение 30 секунд и получить профиль protobuf
curl host:port/debug/pprof/profile?seconds=30 -o profile.pb
# проанализировать профиль в браузере (требуется установленный go)
go tool pprof -web profile.pb

Style Guides

Пожалуйста, следуйте этим рекомендациям при внесении кода в наш проект:

Git Style Guide

Прочитайте руководство по git

Rust Style Guide

Прочитайте правила кодирования

• Используйте cargo +nightly fmt --all, чтобы форматировать код (мы используем group_imports и imports_granularity).

Правила кодирования:

• Если не указано иное, обратитесь к лучшим практикам Rust.

• Используйте стиль mod.rs. Самоназванные модули не пройдут статический анализ, за исключением как trybuild тестов.

• Используйте структуру модулей, ориентированную на домен.

  Пример: не делайте constants::logger. Вместо этого инвертируйте иерархию, поместив объект, для которого он используется, первым: iroha_logger::constants.

• Используйте expect с явным сообщением об ошибке или доказательством безошибочности вместо unwrap.

• Никогда не игнорируйте ошибку. Если вы не можете panic и не можете восстановиться, это, по крайней мере, должно быть записано в журнале.

• Предпочитайте возвращать Result вместо panic!.

• Группируйте связанную функциональность пространственно, предпочтительно внутри соответствующих модулей.

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

• Объявите перед реализацией: операторы use и константы вверху, модульные тесты внизу.

• Старайтесь избегать операторов use, если импортированное имя используется только один раз. Это облегчает перемещение вашего кода в другой файл.

• Не заглушайте clippy линты без разбора. Если вы это сделаете, объясните свою аргументацию комментарием (или сообщением expect).

• Предпочитайте #[outer_attribute] #![inner_attribute], если любой из них доступен.

• Если ваша функция не изменяет ни один из своих входных данных (и она не должна изменять ничего другого), пометьте её как #[must_use].

• Избегайте Box<dyn Error> если возможно (мы предпочитаем строгую типизацию).

• Если ваша функция является геттером/сеттером, пометьте её #[inline].

• Если ваша функция — конструктор (т. е. она создаёт новое значение из входных параметров и вызывает default()), пометьте его #[inline].

• Избегайте привязки вашего кода к конкретным структурам данных; rustc достаточно умён, чтобы превратить Vec<InstructionExpr> в impl IntoIterator<Item = InstructionExpr> и наоборот, когда ему нужно.

Рекомендации по именованию:

• В именах публичных структур, переменных, методов, признаков, констант и модулей используйте только полные слова. Однако сокращения разрешены, если:
  • Имя локальное (например, аргументы замыкания).
  • Название сокращено по соглашению Rust (например, len, typ).
  • Название является общепринятым сокращением (например, tx, wsv и т. д.), TODO ссылка на глоссарий.
  • Полное имя было бы затенено локальной переменной (например, msg <- message).
  • Полное название сделало бы код громоздким с более чем 5-6 словами в нём. Если вы меняете соглашения об именах, убедитесь, что выбранное вами новое имя гораздо понятнее того, что было раньше.

Комментарии к коду:

• При написании комментариев к коду вместо описания того, что делает ваша функция, попробуйте объяснить, почему она делает что-то определённым образом. Это сэкономит ваше время и время рецензента.
• Вы можете оставлять маркеры TODO в коде, если ссылаетесь на проблему, которую вы создали для этого. Отсутствие проблемы означает, что код не будет объединён.

Мы используем закреплённые зависимости. Следуйте этим рекомендациям по управлению версиями:

• Если ваша работа зависит от конкретного ящика, посмотрите, не был ли он уже установлен с помощью команды cargo tree (используйте bat или grep), и попробуйте использовать эту версию вместо последней версии.
• Используйте полную версию «X.Y.Z» в Cargo.toml.
• Предоставляйте обновления версий отдельным PR.

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

• Используйте формат Rust Docs.
• Отдавайте предпочтение однострочному синтаксису комментариев. Используйте /// над встроенными модулями и !/ для файловых модулей.
• Если вы можете сослаться на документацию структуры/модуля/функции, сделайте это.
• Если вы можете предоставить пример использования, сделайте это. Это также тест.
• Избегайте модальных глаголов, если функция может вызвать ошибку или панику. Пример: «Сбой при сбое дискового ввода-вывода» вместо «Может произойти сбой, если случайно произойдёт сбой дискового ввода-вывода».
• Если функция может привести к ошибке или панике по нескольким причинам, используйте маркированный список условий отказа с соответствующими вариантами ошибок (если таковые имеются).
• Функции делают вещи. Используйте повелительное наклонение.
• Структуры являются вещами. Переходите к сути. Например, «Уровень журнала для перезагрузки из среды» лучше, чем «Эта структура инкапсулирует идею уровней ведения журнала и используется для перезагрузки из среды».
• У структур есть поля, которые также являются вещами.
• Модули содержат вещи, и мы это знаем. Переходите к делу. Пример: используйте «Связанные с регистратором черты». вместо «Модуль, который содержит логику, связанную с регистратором».

Контакты

Наши участники сообщества активны в:

Сервис	Ссылка
StackOverflow	https://stackoverflow.com/questions/tagged/hyperledger-iroha
Mailing List	https://lists.lfdecentralizedtrust.org/g/iroha
Telegram	https://t.me/hyperledgeriroha
Discord	https://discord.com/channels/905194001349627914/905205848547155968