Как внести свой вклад

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

Руководства

Общие руководства

Слово "Facil" происходит от испанского слова "легкий", и это качество заложено в самой сути facil.io.

Вклады в facil.io должны быть:

• Легкими в использовании:

  понятный и лаконичный API с макросами, эмулирующими "именованные аргументы" при необходимости.

• Легкими в поддержке:

  • Модульными: даже ценой производительности и даже (хотя менее желательно) ценой соблюдения принципа DRY (Don't Repeat Yourself).

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

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

  • Кратко закомментированными: слишком много комментариев — шум (мы можем читать код), но слишком мало — будущий поддерживатель может не понять причин того, почему был написан данный участок кода.

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

  • Код требует использования услуг kqueue или epoll операционной системы, что означает работу на Linux / BSD / macOS.

  • Код предполагает наличие Unix-подобной среды (форматы файлов и т.д.).

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

• Легкими в компиляцию:

  Код использует GNU make, хотя мы поддерживаем CMake, ни CMake, ни configure не должны быть обязательны на любом этапе.

• Легкими в управление:

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

Руководство сообщества — Будь Добрым

Когда я был ребенком, я не был хорош в общении с людьми (не уверен, что лучше стало со временем...)... Именно поэтому я научился хорошо работать с компьютерами, и благодаря этому у нас есть facil.io и другие проекты открытого программного обеспечения! Однако, я обещаю сделать всё возможное, чтобы быть добросовестным коммуникатором и прошу вас также приложить усилия для этого.Независимо от того, обсуждаете ли вы запрос на включение (PR, где мы можем найти себя в жарких спорах) или отвечаете на проблему (где иногда мы задумываемся, почему люди считают нас их слугами)... нам всем следует помнить, что немного сочувствия и уважения может многое значить.### Гайдлайн стилей и руководства

Несколько указаний относительно стилистики кода (игровое слово).

• Используйте clang-format с стилем LLVM.

• Инициализируйте все переменные при объявлении — даже если это избыточно.

• Используйте goto, чтобы перемещать ветви кода в конец тела функции.

  Это делает основное тело функции более читаемым (на мой взгляд) и должно помочь с прогнозированием ветвлений (похоже на то, как помогает unlikely, но использует другой подход).

Быстрый обзор

facil.io состоит из следующих модульных «семейств»:

• Ядро:

  Это семейство модулей составляет ядро facil.io. Хотя его можно использовать вне facil.io (в большинстве случаев), ни один из этих модулей не может быть удален.

  Модуль состоит из двух файлов: fio.h и fio.c.

  Файл fio.h можно включать несколько раз и он включает некоторые базовые типы, такие как поддержка двоичной строки, массивы, хэш-таблицы, спинлоки и т.д. (см. документацию).

• Динамические типы (FIOBJ) с нативной поддержкой JSON.

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

  В отличие от большинства модулей, этот модуль является факультативным только в том случае, если используется независимо от ядра.

• HTTP / WebSockets:

  Папка http относится к связанному HTTP/WebSocket расширению / модулю. Несмотря на то, что это семейство модулей кажется сильно связанным, я сделал всё возможное, чтобы сделать его легко поддерживаемым и расширяемым с минимальным количеством взаимосвязей.

  Модули HTTP-запросов и ответов поддерживают таблицы виртуальных функций для будущих расширений HTTP/2. Реализация запросов/ответов может различаться между протоколами реализации, но их интерфейсы должны быть версионно агнозными.

  Как большинство модулей, этот модуль является факультативным и может быть удалён из facil.io без побочных эффектов.

• Redis:

  Двигатель Redis находится в своей папке, как потому, что он явно является «расширителем» (хотя это и публичный/подписной расширитель), так и потому, что он является самым факультативным из всех. Это также хороший пример моего предпочтения модульной архитектуры. Парсер RESP представляет собой библиотеку в одном файле. Его легко можно перенести в различные проекты, и он полностью отделён от сетевого слоя.

• CLI:

  Расширение / модуль командной строки находится в папке cli и следует рассматривать как опциональное дополнение. Другие модули не должны зависеть от его наличия или отсутствия.

  Это тоже, как и модуль Redis, является хорошим примером предпочитаемого модульного подхода.

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

Добавьте функцию, которую вы хотите реализовать, в следующий список (или назначьте существующую функцию себе). Это позволит нам обсуждать, в потоке pull request, любые вопросы, которые у вас могут возникнуть, или ожидания, которые могут повлиять на API или функцию.

Как только у вас будет вся информация, необходимая для реализации функции, обсуждение может перейти к самому pull request функции.

Это те функции, которые были запрошены до сих пор. Даже если некоторые из них уже назначены, не стесняйтесь предложить свою помощь:| Функция | Назначен | Примечание | |-------------------|--------------------|------------------------------| | Документация | 🙏 Помощь 🙏 | Размещена в docs/_SOURCE | | Тесты | Никогда недостаточно | Выполняются через tests.c, но реализуются в исходных файлах. | | Early Hints HTTP/1.1 | | | | SSL/TLS | | Посмотрите пример в fio_tls_missing.c | | WebSocket Клиент | | Отсутствие хранения cookies | | HTTP Клиент | | Отсутствие SSL/TLS, хранения cookies и автоматического перенаправления (?) | | HTTP/2 | | | | HTTP Роутер | | RESTful без использования регулярных выражений. Например: /users/(:id) | | PostgreSQL | | Обёртка libpq.h для событий + движка pub/sub (?) | | Gossip (?) | | Для масштабирования движка pub/sub |## Лицензия

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

Я обнаружил, что GitHub не предлагает стандартное соглашение о правах использования и лицензировании (CLA), поэтому я использовал тот, который используется в BearSSL, то есть:

• результирующий код использует лицензию MIT, указывая меня (и только меня) как автора. Вы можете взять на себя заслугу, заявив, что код был написан вами, но должны приписать права собственности и авторство мне (Боаз Сегев). Это аналогично подходу "работа за найм".

• Я буду упоминать значимые вклады в CHANGELOG, а особенные вклады будут указаны в README и/или здесь.

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

Значимые Вклады

• @area55git (Area55) предоставил логотип под лицензией Creative Commons Attribution OnClickListener 4.0 International.

• @cdkrot уделил время тестированию части демонстрационного кода с помощью valgrind, выявив проблему закрытия с внутренней библиотекой defer и предложив быстрое исправление.* @madsheep и @nilclass уделили время выявлению очень скрытой ошибки (#16), связанной с длительным процессированием on_open обратного вызова websocket и очень короткими сетевыми временами ожидания, выявив слабость в логике HTTP/1.x.

• @64 уделил время тестированию предварительно выпущенной версии 0.6.0 и представлению PR #25, исправив незаметную ошибку и несколько предупреждений.

• Флориан Вебер (@Florianjw) уделил время проверке черновика RiskyHash и выявлению ошибки порядка байтов (порядок чтения последних 7 байт).

• Крис Андерсон (@injinj) проделал отличную работу исследования варианта 128 бит и атаки на RiskyHash с использованием варианта метода встречи посередине, написанного Хенингом Макхолмом (@hmakholm) в его (ветке SMHasher). Черновик RiskyHash был обновлен для решения этой атаки.