Методические указания для контрибьюторов

Пожалуйста, следуйте перечисленным ниже правилам, внося свой вклад в RimSort.

Содержание

1. Методические указания для контрибьюторов
   1. Содержание
   2. Основные правила
   3. Версии и релизы
      1. Описание релизов и пайплайн
      2. Ключевые слова и шаблоны версий
      3. Ограничения и возможные проблемы
         1. Возможное состояние гонки
   4. Разработка функций
   5. Запуск задач
   6. Стиль кода
      1. Линтинг и форматирование
      2. Соглашения

Основные правила

1. Pull request’ы должны создаваться ТОЛЬКО после выполнения всех правил. Некоторые недочёты допустимы — мы можем отловить их при ревью, однако мы ожидаем аккуратного подхода к docstring’ам, форматированию кода и т. п. Если готовности ещё нет, используйте draft.

2. Пожалуйста, отправляйте pull request’ы, которые содержат только изменения по одной конкретной функции. PR’ы не должны сваливать несколько изменений в одно. Это необходимо для более избирательного обсуждения. Требование обязательное — отклонение приведёт к закрытию PR.

3. Перед запросом ревью убедитесь, что ваш pull request проходит базовые проверки линтера и Pytest. Если нет — это будет первым, что мы попросим исправить.

4. В репозитории RimSort есть шаблоны для Issues на GitHub. Отчёты об ошибках и запросы функций оформляются там; если по запросу достигнуто согласие, он становится Issue вида «Реализовать: …». Пожалуйста, не отходите от шаблона и позволяйте мейнтейнерам дорабатывать Issue, добавляя релевантные задачи и информацию в заголовок после достижения консенсуса.

   • Консенсус = консенсус мейнтейнеров. При этом мы рассчитываем на вашу обратную связь, так что ваш голос важен.
   • Вы также можете форкнуть этот репозиторий и вносить любые изменения в частном порядке.
5. КАЖДОМУ PR требуется соответствующая Issue и/или подзадача(и) для ссылки. Это необходимо для прозрачности и помогает всем остальным, кто участвует, отслеживать прогресс.
   • Участвовать может любой желающий. Мы сообщество, и эти правила помогают поддерживать единообразие по мере роста RimSort.
   • Мейнтейнер или нет — для отправки PR не обязательно быть мейнтейнером! Не стесняйтесь работать из форка или другим удобным способом.

6. В 99% случаев не стоит отправлять pull request’ы, которые только обновляют зависимости. Базовые обновления зависимостей автоматически обрабатываются dependabot.

7. RimSort поддерживает флаг --dev, который перенаправляет все данные в подкаталог dev/ репозитория, не затрагивая вашу рабочую конфигурацию. Подробности см. в разделе Настройке окружения разработчика.

Версии и релизы

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

Ручные теги должны начинаться с v и соответствовать формату релиза, например v1.1.1.

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

Отслеживаемые каталоги

• app
• libs
• submodules
• themes

Описание релизов и пайплайн

Тип	Формат версии	Триггер	Описание
Release	v${major}.${minor}.${patch}	Вручную	Версии, которые можно безопасно использовать и которые считаются стабильными.
Edge	v${major}.${minor}.${patch}-edge${increment}+${short-sha}	Вручную	Версии, выпускаемые часто, с новейшими функциями и исправлениями, но с возможными серьёзными багами.
Auto-Build	v${major}.${minor}.${patch}-auto${increment}+${short-sha}	Авто	Версии, создаваемые пайплайном автоматической сборки при каждом pull request’е и пуше в main. Не публикуются. Сборки хранятся как артефакты.

Релизы создаются ручным запуском соответствующего GitHub workflow’а. Для безопасности рекомендуется создавать релиз как черновик (draft).

Edge-релизы перезаписываются: создаётся новый edge-тег, а старый релиз полностью удаляется. Стабильные релизы не перезаписываются. По умолчанию нечерновые стабильные релизы защищены, и авто-action завершится с ошибкой, если релиз с таким же тегом уже существует.

Если по какой-то причине шаг сборки завершился, но остальные шаги пайплайна релиза завершились с ошибкой, вы можете перезапустить workflow с переопределением, пропустив шаг сборки, передав action’у ID запуска (run ID), из артефактов которого будут взяты сборки для релиза.

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

Ключевые слова и шаблоны версий

Тип	Шаблон	Описание
major	(major)	Крупные и ломающие обновления
minor	(minor)	Небольшие обновления. Не ожидается ломающих изменений, но могут появиться новые функции и крупные исправления багов
patch	н/д (неявно)	Небольшие изменения без ломающих последствий. Увеличивается на PR, если нет других шаблонов.
increment	н/д (неявно)	Количество коммитов с момента последнего изменения версии
short-sha	н/д (неявно)	Первые семь символов sha-идентификатора коммита, из которого собрана версия

Ограничения и возможные проблемы

Возможное состояние гонки

Из-за особенностей среды GitHub runner’ов существует вероятность гонки, если коммит попадёт в ветку, на которой работает action сборки и релиза. Если ветка изменяется во время работы action’а, в зависимости от шага action’а информация о версии в релизе и коммит, используемый для сборки, могут различаться. В особо неудачном случае, когда один runner для конкретной цели сборки уже загрузил и выгрузил коммит, но до других runner’ов для других целей был запушен новый коммит, сборки для различных целей могут оказаться на разных коммитах.

Обратите внимание, что фактическая версия из version.xml и сообщаемая приложением версия всегда будут корректными.

Чтобы снизить риск, информация о версии для пайплайна релиза снимается в первую очередь, до начала сборок и тестирования. Кроме того, непосредственно перед релизом выполняется проверка несоответствия коммитов. Если целевые коммиты любого артефакта не совпадают с коммитом релиза, workflow по умолчанию завершается с ошибкой.

Разработка функций

Если у вас есть запрос функции, сначала проверьте, не запланирована ли она уже. Мы отслеживаем функции и Issues, связанные с RimSort, во вкладке «Issues» репозитория GitHub. Если её там нет, вы можете обсудить её с мейнтейнерами на сервере Discord RimSort.

Запуск задач

В качестве инструмента запуска задач мы используем just. Запустите just без аргументов, чтобы получить список всех доступных рецептов.

Ключевые рецепты для контрибьюторов:

Команда	Описание
just check	Запустить все проверки качества кода (ruff, ruff-format, typecheck, pyright, jscpd, shfmt, markdownlint)
just fix	Автоисправление ошибок линтинга и форматирования
just test	Запуск тестов с включёнными модулями doctest
just test-coverage	Запуск тестов с отчётами о покрытии (XML, HTML, терминал)
just test-verbose	Запуск тестов с подробным выводом и короткими traceback’ами
just ruff	Проверка кода на ошибки линтинга (ruff check)
just ruff-format	Проверка форматирования кода (ruff format)
just ruff-fix	Автоисправление ошибок линтинга (ruff check –fix)
just ruff-format-fix	Автоисправление форматирования (ruff format)
just typecheck	Проверка статических типов (mypy)
just pyright	Проверка статических типов (pyright)
just jscpd	Обнаружение копирования кода (нулевая толерантность)
just shfmt	Проверка форматирования shell-скриптов (shfmt, только diff)
just shfmt-fix	Автоисправление форматирования shell-скриптов (shfmt -w)
just markdownlint	Проверка Markdown-файлов (markdownlint-cli2)
just markdownlint-fix	Автоисправление Markdown-файлов (markdownlint-cli2 –fix)
just clean	Удаление артефактов сборки, кэшей и сгенерированных файлов
just run	Запуск приложения RimSort
just dev-setup	Установка всех зависимостей, включая группы dev и build
just build	Сборка исполняемого файла RimSort (инициализирует сабмодули, запускает проверки)
just build-version VERSION	Сборка с конкретной строкой версии, напр. “1.2.3.4”
just update	Обновление всех зависимостей до последних совместимых версий
just submodules-init	Инициализация и обновление git-сабмодулей (после клонирования)
just build-help	Справка для скрипта сборки distribute.py
just ci	Полный локальный запуск CI-пайплайна (проверки + тесты + покрытие)

Запустите just check перед отправкой PR. CI выполняет все эти проверки и завершится с ошибкой, если что-то не так.

Стиль кода

Линтинг и форматирование

• Ruff используется как для линтинга, так и для форматирования (just ruff + just ruff-format).
  • Расширение VS Code
  • Ruff заменяет isort, flake8 и black. Отключите их, если они установлены.
  • Конфигурация находится в pyproject.toml.
• mypy используется для проверки статических типов (just typecheck).
  • Расширение VS Code
• JSCPD используется для обнаружения копирования кода (just jscpd).
  • CI требует 0% дублирования. Если у вас есть похожие блоки кода, вынесите общий вспомогательный код.
• Для shell-скриптов используется shfmt.
  • Расширение VS Code
• markdownlint-cli2 используется для линтинга Markdown (just markdownlint).
  • Расширение VS Code
  • Конфигурация находится в .markdownlint.json (правила, общие с Nix pre-commit-хуком) и .markdownlint-cli2.jsonc (опции CLI2).

Соглашения

• Предпочтительный формат docstring — Sphinx reST
• К сигнатурам функций/методов следует добавлять аннотации типов.
  • Используйте стандарты Python 3.10+. (Избегайте импорта typing. PEP 604 вместо Optional)
• Настройки рабочего пространства VS Code включены в репозиторий