Внесение вклада в проект Rocket

Пожалуйста, прочитайте этот документ перед тем как начать вносить свой вклад!

Спасибо за ваш вклад! Мы рады принимать ваши предложения независимо от формы, в которой они представлены.

Этот документ предоставляет руководства и ресурсы, чтобы помочь вам успешно внести свой вклад в проект. Rocket — это инструмент, созданный с целью расширять границы удобства, безопасности и производительности веб-фреймворков, а значит наши требования к качеству высоки. Чтобы максимально использовать время каждого участника и избежать потраченных зря усилий, уделите внимание нашим ожиданиям и конвенциям, описанным ниже.

Отправка запросов на слияние

Перед созданием нового запроса на слияние:

• Прочитайте и понимайте [Конвенции стиля кода], [Руководство по составлению сообщений коммитов] и [Тестирование].

• Если вы решаете открытую проблему, следуйте [Решению открытой проблемы].

• Если вы внедряете новую функциональность, проверьте, было ли предложено ранее реализовать ту же функциональность, как [проблема] или [запрос на слияние]. Убедитесь, что ваш запрос на слияние решает любые ранее возникшие вопросы. Затем следуйте [Внедрению недопрошенной функции].

• Для всего остального, см. [Другие общие вклады].Мы стремимся поддерживать качество кода проекта Rocket на самом высоком уровне. Это означает, что любой код, который вы вносите, должен удовлетворять следующим условиям:

• Прокомментирован: сложная или тонкая функциональность должна быть правильно прокомментирована.

• Документирован: публичные элементы должны иметь документальные комментарии с примерами.

• Стилизован: ваш код должен соответствовать [Конвенциям стиля кода].

• Прост: ваш код должен выполнять свою задачу наиболее просто и типично.

• Тестирован: вы должны написать (и пройти) убедительные тесты для всех новых или изменённых функций.

• Оriented to purpose: ваш код должен делать то, что ему предназначено, и ничего больше.

Решение открытой проблемы

Если вы заметили открытую проблему, которую хотите решить:

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

Тестирование

[Тестирование]: #тестирование Если есть, переходите к шагу 2. Если нет, первым делом до того как начать писать код, предложите решение. Для этого оставьте комментарий, описывающий ваше решение в соответствующей задаче. Особенно полезно видеть тестовые случаи и гипотетические примеры. Этот шаг критичен: он позволяет нам идентифицировать и решать вопросы относительно предложенного решения до того, как кто-либо потратил время на написание кода. Он также может указывать более эффективные направления для реализации.

2. Напишите проваливающийся тестовый случай, который вы ожидаете пройти после решения задачи. Если вы можете написать правильные тестовые случаи, которые проваливаются, сделайте это (см. [Тестирование]). Если нет, например, потому что вы вводите новые API, которые ещё не существуют, напишите тестовый случай, который имитирует использование этих API. В любом случае, позвольте тестам и примерам имитации направлять ваш прогресс.

3. Напишите базовую функциональность, пройдите тесты и отправьте pull request.

   Подумайте о граничных случаях для задачи и убедитесь, что у вас есть тесты для этих граничных случаев. Как только ваша реализация будет функционально завершена, отправьте pull request. Не тратите время на написание или изменение большого количества документации пока.

4. Подождите отзыв, итерируйтесь и доведите до совершенства.

   Если отзыв не приходит за несколько дней, не стесняйтесь обратиться к поддержке проекта. Как только кто-то проверяет ваш pull request, учтите его отзывы. Если pull request решает проблему (что должно быть так, поскольку у вас есть проходящие тесты) и соответствует проекту (что должно быть так, поскольку вы просили отзывы до отправки), он будет условно одобрен с учётом окончательной доработки: документация (rustdocs, руководство), улучшение стиля и тестирование. Ваш pull request затем будет объединён.

Реализация непредложенного функционала

[Реализация непредложенного функционала]: #реализация-непредложенного-функционалаПрежде всего, пожалуйста, не отправляйте pull request, который реализует новую функцию, без предварительного предложения дизайна и получения отзыва. Мы очень серьезно относимся к добавлению новых функций, так как они напрямую влияют на удобство использования.

Чтобы предложить новую функцию, создайте [новый запрос на функцию] и следуйте шаблону. Обратите внимание, что некоторые категории функций требуют особенно убедительного обоснования для рассмотрения. Это включает функции, которые:

• могут быть реализованы вне Rocket;
• вводят новые зависимости, особенно более тяжёлые;
• существуют только для добавления поддержки внешнего crate;
• слишком специфичны для одного случая использования;
• оверкомплексны и имеют "простые" обходные пути;
• только частично решают большую недостаточность.

Как только ваш запрос на функцию будет принят, следуйте [Решению открытых вопросов].

[новый запрос на функцию]: https://github.com/rwf2/Rocket/issues/new?assignees=&labels=request&projects=&template=feature-request.yml### Другие распространённые вклады [Другие распространённые вклады]: #другие-распространённые-вклады

• Исправление документов, исправление опечаток, улучшение формулировок. Мы приветствуем любой из этих вкладов! Просто отправьте Pull Request с вашими изменениями. Пожалуйста, сохраните окружающее форматирование markdown, насколько это возможно. Обычно это означает сохранение строк менее 80 символов, выравнивание разделителей таблиц и сохранение отступов соответственно. Исходные файлы руководства находятся в [docs/guide]. Обратите внимание на следующий специальный синтаксис, доступный в markdown руководства:

  • Перекрестная ссылка страниц осуществляется через относительные ссылки. Вне индекса это выглядит так: ../{page}#anchor. Например, чтобы ссылаться на Быстрый старт > Запуск примеров, используйте ../quickstart#running-examples.
  • Альтернативные адреса — это краткие URL-адреса, начинающиеся с @ (например, @api). Они используются во всем руководстве для упрощения создания версионированных URL-адресов. Они заменяются при сборке соответствующей версионированной экземпляром.

• Новые примеры или изменения существующих.

  Пожалуйста, следуйте процессу [Реализация непредложенного функционала].

• Форматирование или другие чисто косметические изменения.

  Мы обычно не принимаем чисто косметические изменения в кодовой базе, такие как стиль или форматирование. Все Pull Requests должны добавлять что-то实质性的东西到Rocket的功能、连贯性、测试、性能、可用性、错误修复、安全性、文档或整体可维护性。

• Объявления любого типа.

  Мы не принимаем никаких вкладов, которые похожи на рекламу или продвижение. Если вас интересует поддержка Rocket, мы рекомендуем вам [спонсировать проект].

Тестирование

[Тестирование]: #тестированиеВсе тестирование происходит через [test.sh]. Перед отправкой Pull Request запустите скрипт и устраните все проблемы. По умолчанию используется режим (передача без аргументов или --default), который обычно достаточно, но вы также можете захотеть выполнить дополнительные тесты. В частности:

• Если вы делаете изменения в contrib: test.sh --contrib
• Если вы делаете изменения в пользовательском интерфейсе API или обновляете зависимости: test.sh --examples
• Если вы добавляете или модифицируете флаги функций: test.sh --core
• Если вы изменяете кодогенерацию: см. [UI Tests].

Запустите test.sh --help, чтобы получить общее представление о том, как выполнять скрипт:

ИСПОЛЬЗОВАНИЕ:
  ./scripts/test.sh [+<TOOLCHAIN>] [--help|-h] [--<TEST>]

ПАРАМЕТРЫ:
  +<TOOLCHAIN>   Передается в Cargo для выбора компилятора.
  --help, -h     Выводит это сообщение помощи и завершает выполнение.
  --<TEST>       Выполняет указанное тестовое множество.
                 (Выполнение без --<TEST> запустит тесты по умолчанию.)

ДОСТУПНЫЕ ПАРАМЕТРЫ ТЕСТА:
  default
  all
  core
  contrib
  examples
  benchmarks
  testbench
  ui

ПРИМЕРЫ:
  ./scripts/test.sh                     # Выполняет тесты по умолчанию с текущего компилятора.
  ./scripts/test.sh +stable --all       # Выполняет все тесты с использованием стабильной версии компилятора.
  ./scripts/test.sh --ui                # Выполняет UI тесты с текущего компилятора.

Написание тестовRocket проверяется различными способами. Это включает использование регулярных средств тестирования Rust, таких как doctests, модульные тесты и интеграционные тесты, а также специальные тесты Rocket:

• Примеры: Директория examples содержит приложения, использующие многие возможности Rocket. Каждый пример интегрировано протестирован с помощью встроенной локальной системы тестирования Rocket. Это гарантирует, что типичный код Rocket продолжает работать так, как ожидался, и служит способом выявления и решения пользовательских проблем.

• Testbench: Testbench Rocket (testbench) проверяет конечные свойства сервера или протокола путём запуска полных серверов Rocket, которым отправляются реальные HTTP-запросы. Каждый сервер независимо написан в testbench/src/servers/. Вам скорее всего потребуется написать тест bench только если вы изменяете низкоуровневые детали.

• UI Тесты: UI тесты обеспечивают, что генерация кода Rocket производит значимые диагностические сообщения компилятора. Они компилируют приложения Rocket и сравнивают вывод компилятора с ожидаемыми результатами. При изменении генерации кода вам потребуется обновить или создать UI тесты. Подробнее см. [UI Тесты].Для любого изменения, которое влияет на функциональность, мы просим вас написать тест, который будет проверять эту функциональность. Минимально, это должно быть модульное тестирование, doctest, интеграционное тестирование или их сочетание. Для небольших изменений, модульные тесты, скорее всего, будут достаточно. Если изменение влияет на пользователя каким-либо образом, то должны быть добавлены или изменены doctests. А если изменение требует использования различных API для тестирования, то следует добавить интеграционное тестирование. Кроме того, следующие сценарии требуют особого внимания: - Улучшенные возможности

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

• Новые возможности

  Для крупных возможностей полезно представить новый пример, демонстрирующий типичное использование этой возможности. Убедитесь, что вы также отредактировали README в директории examples. Кроме того, все новые публичные API должны быть полностью документированы и содержать doctests, а также юнит-тесты и интеграционные тесты.

• Исправление ошибки

  Чтобы избежать регрессий, всегда добавляйте или изменяйте интеграционный или тестовый стенд тест для исправления ошибки. Интеграционные тесты должны находиться в обычной директории tests/ и иметь имя в формате short-issue-description-NNNN.rs, где NNNN — это номер задачи на GitHub для данной ошибки. Например, forward-includes-status-1560.rs.

UI-тесты

Изменения в кодогене (то есть, rocket_codegen и другие _codegen crate) требуют добавления и запуска UI-тестов, которые захватывают вывод компилятора и сравнивают его с ожидаемым выходом. UI-тесты используют [trybuild].Тесты можно найти в директориях codegen/tests/ui-fail, соответствующих crate codegen. Каждый тест является символьной ссылкой в соседние директории ui-fail-stable и ui-fail-nightly, которые также содержат ожидаемый вывод ошибок для стабильного и нightly компиляторов соответственно. Например:``` ./core/codegen/tests ├── ui-fail │ ├── async-entry.rs │ ├── ... │ └── uri_display_type_errors.rs ├── ui-fail-nightly │ ├── async-entry.rs -> ../ui-fail/async-entry.rs │ ├── async-entry.stderr │ ├── ... │ ├── uri_display_type_errors.rs -> ../ui-fail/uri_display_type_errors.rs │ └── uri_display_type_errors.stderr └── ui-fail-stable ├── async-entry.rs -> ../ui-fail/async-entry.rs ├── async-entry.stderr ├── ... ├── uri_display_type_errors.rs -> ../ui-fail/uri_display_type_errors.rs └── uri_display_type_errors.stderr

Если вы вносите изменения в кодоген, запустите тесты UI для стабильной версии и ночного сборка с помощью команд
`test.sh +stable --ui` и `test.sh +nightly --ui`. В случае возникновения ошибок, обновите выходные данные с помощью команд
`TRYBUILD=overwrite test.sh +nightly --ui` и `TRYBUILD=overwrite test.sh +stable --ui`. Посмотрите разницу, чтобы понять, что изменилось. Убедитесь, что сообщения об ошибках правильно указывают источник ошибки (то есть визуально подчеркивают или указывают на него). Например, если типу требуется реализовать определённый трейт, то этот тип следует подчеркнуть. Мы стремимся генерировать максимально полезные и информативные сообщения об ошибках.

### Документация APIЕсли вы вносите изменения в документацию, вам следует создать документацию API и проверить, что ваши изменения соответствуют вашим ожиданиям. Документация API создаётся с помощью скрипта [mk-docs.sh](#api-docs) и выводится в обычную директорию `target/docs`. По умолчанию скрипт очистит любую существующую документацию, чтобы избежать возможных проблем с кэшированием. Чтобы переопределить это поведение, используйте `mk-docs.sh -d`.## Конвенции стиля кода
[Конвенции стиля кода]: #code-style-conventions

Мы **не используем** `rustfmt` или `cargo fmt` из-за багов и отсутствия некоторых функций. Вместо этого мы просим вас следовать [Руководству по стилю Rust], с некоторыми изменениями:

**Всегда разделяйте элементы одним пустым столбцом.**

| ✅ Да | Нет 🚫 |
| --- | --- |
| ```rust fn foo() { // .. } fn bar() { // .. } ``` | ```rust fn foo() { // .. }fn bar() { // .. } ``` |

**Предпочтительно использовать конструкцию `where` вместо блочного отступа для шаблонов.**

| ✅ Да | Нет 🚫 |
| --- | --- |
| ```rust fn foo<T, U>(x: Vec<T>, y: Vec<U>) where T: Display, U: Debug { // .. } ``` | ```rust fn foo< T: Display, U: Debug, >(x: Vec<T>, y: Vec<U>) { // .. } ``` |

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

| ✅ Да | Нет 🚫 |
| --- | --- |
| ... | ... |```rust
fn foo<T, F, Item, G>(v: Foo<T, F, Item>) -> G
    where T: for<'x> SomeTrait<'x>,
          F: Fn(Item) -> G,
          Item: Display + Debug,
          G: Error,
{
    // ..
}

fn foo<T, F, Item, G>(v: Foo<T, F, Item>) -> G
    where
        T: for<'x> SomeTrait<'x>,
        F: Fn(Item) -> G,
        Item: Display + Debug,
        G: Error,
{
    // ..
}

Не используйте многострочные импорты. Группируйте импорты по типу, если это возможно.

Сортировка импортов в порядке уменьшения "расстояния" до текущего модуля: std, core, и alloc, внешние пакеты, затем текущий пакет. Предпочтительно использовать относительные импорты с помощью crate вместо super. Разделите каждую категорию одним пустым столбцом.

use std::{foo, bar};
use alloc::{bar, baz};

use either::Either;
use futures::{SomeItem, OtherItem};

use crate::{item1, item2};
use crate::module::item3;
use crate::module2::item4;

use crate::{item1, item2};
use std::{foo, bar};
use either::Either;
use alloc::{bar, baz};
use futures::{SomeItem, OtherItem};

use super::{item3, item4};
use super::item4;

Правила составления сообщений коммита

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

    - Пример: `Исправление 'TcpListener': разрешение префикса 'tcp://' вместо 'udp://'.`
  * **Улучшение** — для небольших улучшений функциональности или документации
    - Пример: `Улучшение сообщений ошибок при выводе 'FromParam'.`
  * **Введение** — для крупных введений новых функций
    - Пример: `Введение поддержки WebSockets.`
  * **Добавление**, **Удаление** — для изменений
    - Пример: `Добавление конструктора 'Foo::new()'.`
    - Пример: `Удаление 'Foo::new()'; добавление 'Foo::build()'.`
  * **Обновление** — для обновлений пакета
    - Пример: `Обновление 'base64' до версии 0.12.`
  * **Реализация** — для реализации трейтов
    - Пример: `Реализация 'FromForm' для 'ThisNewType'.`

Обратите внимание, как слова общего назначения, такие как "изменение", избегаются, а заголовки конкретизируются относительно сделанных изменений. Вам не обязательно ограничиваться этим словарём. В случае сомнений обратитесь к `git log` за примерами.| **✅ Да**                                             | **Нет 🚫**                                |
|--------------------------------------------------------|-------------------------------------------|
| Исправление опечатки 'yis' -> 'yes' в документации 'FromForm'. | Изменение слова в документации            |
| Установка по умолчанию 'MsgPack<T>' на именованную вариацию. | Изменение значения по умолчанию на более вероятную вариацию. |
| Исправление совета 'Compact' в документации 'MsgPack'. | Обновление документов для большей понятности |
| Улучшение документации 'Sentinel': объяснение 'Sentry'. | Добавление недостающих деталей документации. |
| Исправление CI: закрепление версии 'mysql-client' на '8.4' в CI macOS. | Исправление CI                             |
| Исправление ссылки на 'rocket::build()' в руководстве по конфигурации. | Исправление неверной ссылки в руководстве (конфигурация). |**Основная часть** должна описать, что делает коммит. Например, если коммит представляет новую функцию, он должен описать, какие возможности она предоставляет и как они предоставляются. Основная часть может быть не нужна, если заголовок достаточно точно описывает коммит. Избегайте ссылок на задачи в основной части; мы это сделаем в нижней части. Если вы ссылаетесь на другой коммит, используйте только его короткий хэш. Вы можете использовать markdown, включая списки и код.

Наконец, **нижняя часть** предназначена для ссылок на задачи. Посмотрите документацию GitHub по [связыванию задач](https://docs.github.com/en/github/managing-your-content/autolink-reference-for-github#linked-issues). [связанные задачи]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
[Руководство по стилю Rust]: https://doc.rust-lang.org/nightly/style-guide/
[задача]: https://github.com/rwf2/Rocket/issues
[предложение изменений]: https://github.com/rwf2/Rocket/pulls
[test.sh]: scripts/test.sh
[mk-docs.sh]: scripts/mk-docs.sh
[`trybuild`]: https://docs.rs/trybuild
[поддержать проект]: https://github.com/sponsors/rwf2
[docs/guide]: docs/guide

## Лицензия

Если вы явно не указываете иное, любой вклад, намеренно представленный вами для включения в Rocket, будет двойной лицензирован под лицензией MIT и Apache License, Версия 2.0, без каких-либо дополнительных условий или требований.Документация сайта Rocket лицензируется под [отдельными условиями](docs/LICENSE). Любое вклад, намеренно представленное вами для включения в документацию сайта Rocket, будет лицензировано под эти условия.