.. _root_contributing: Вклад в проект ============== .. default-role:: code Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️ Мы приветствуем и ценим любой вклад. Пожалуйста, прочтите соответствующий раздел, прежде чем начать. Это облегчит работу мейнтейнеров и сделает процесс более гладким для всех. Сообщество с нетерпением ждёт ваших идей! 🎉 .. note:: Если вам нравится проект, но у вас нет времени на активный вклад, вы можете поддержать нас другими способами: * Поставить звезду на GitHub. * Написать о проекте в Twitter или других социальных сетях. * Сослаться на проект в `README` вашего репозитория. * Упомянуть проект на митапах и рассказать о нём друзьям и коллегам. .. _Содержание: Содержание ---------- * `Кодекс поведения`_ * `У меня есть вопрос`_ * `Я хочу внести вклад`_ * `Сообщение об ошибках`_ * `Предложение улучшений`_ * `Ваш первый вклад в код`_ * `Улучшение документации`_ * `Руководства по стилю`_ * `Сообщения коммитов`_ * `Присоединяйтесь к команде проекта`_ .. _Кодекс поведения: Кодекс поведения ---------------- Этот проект и все его участники руководствуются :ref:`Кодексом поведения Argenta `. Участвуя, вы обязуетесь соблюдать этот кодекс. Пожалуйста, сообщайте о недопустимом поведении. ----- .. _У меня есть вопрос: У меня есть вопрос ------------------ .. note:: Прежде чем задать вопрос, пожалуйста, ознакомьтесь с `документацией `_. Поищите ответ в существующих `Issues `_. Если вы нашли похожий вопрос, но всё ещё нуждаетесь в разъяснениях, можете написать в нём. Также рекомендуем поискать ответ в интернете. Если ответа не нашлось, создайте новый `Issue `_ и предоставьте как можно больше контекста, включая версии проекта и платформы (CPython, pip и т.д.). Мы займемся вашей задачей как можно скорее. ----- .. _Я хочу внести вклад: Я хочу внести вклад ------------------- .. rubric:: Правовое уведомление .. note:: Внося вклад в этот проект, вы подтверждаете, что являетесь автором 100% контента, обладаете необходимыми правами на него и соглашаетесь, что он может распространяться под лицензией проекта. .. _Сообщение об ошибках: Сообщение об ошибках -------------------- .. rubric:: Перед отправкой отчета об ошибке Хороший отчёт об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Пожалуйста, тщательно всё изучите, соберите информацию и подробно опишите проблему. Это поможет нам исправить её как можно быстрее. * Убедитесь, что вы используете последнюю версию. * Убедитесь, что проблема действительно является ошибкой, а не вызвана, например, использованием несовместимых версий окружения. Прочтите `документацию `_ и, если нужна поддержка, загляните в раздел `У меня есть вопрос`_. * Проверьте, нет ли уже отчёта о вашей ошибке в `трекере `_. * Также поищите в интернете (включая `Stack Overflow`), чтобы узнать, обсуждалась ли проблема за пределами `GitHub`. * Соберите информацию об ошибке: * Трассировка стека. * ОС, платформа и версия (Windows, Linux, macOS, x86, ARM). * Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов и т.д. * Входные данные и полученный результат. * Можете ли вы надёжно воспроизвести проблему? Воспроизводится ли она на старых версиях? .. rubric:: Как мне отправить хороший отчет об ошибке? .. note:: Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках с конфиденциальной информацией в публичном трекере. Для этого используйте электронную почту. Мы используем `GitHub Issues` для отслеживания ошибок. Если вы столкнулись с проблемой: * Откройте новый `Issue `_. На этом этапе не нужно присваивать ему метки. * Объясните ожидаемое и фактическое поведение. * Предоставьте как можно больше контекста и опишите **шаги для воспроизведения**, чтобы проблему можно было воссоздать. Лучше всего изолировать её и создать минимальный тестовый пример. * Предоставьте информацию, которую вы собрали в предыдущем разделе. После того, как задача будет создана: * Команда проекта присвоит задаче соответствующую метку. * Член команды попытается воспроизвести проблему. Если шагов нет или они не приводят к результату, команда попросит вас предоставить их и пометит задачу как `needs-repro`. Такие задачи не будут рассматриваться до тех пор, пока проблема не будет воспроизведена. * Если проблема будет воспроизведена, она будет помечена как `needs-fix` (и, возможно, другими метками, например `critical`), после чего её сможет взять в работу :ref:`любой желающий <Ваш первый вклад в код>`. ----- .. _Предложение улучшений: Предложение улучшений --------------------- Этот раздел поможет вам отправить предложение по улучшению `Argenta`, **включая как новые функции, так и незначительные улучшения**. Следование этим рекомендациям поможет мейнтейнерам и сообществу лучше понять вашу идею. .. rubric:: Перед отправкой предложения по улучшению * Убедитесь, что вы используете последнюю версию. * Внимательно прочтите `документацию `_ и убедитесь, что предлагаемая функциональность ещё не реализована (возможно, через конфигурацию). * Выполните `поиск `_, чтобы проверить, не предлагалось ли это улучшение ранее. Если да, добавьте комментарий к существующей задаче. * Определите, соответствует ли ваша идея масштабу и целям проекта. Вам предстоит убедительно доказать её пользу. Мы хотим видеть функции, которые будут полезны большинству пользователей. Если ваша идея ориентирована на узкий круг, рассмотрите возможность создания плагина. .. rubric:: Как мне отправить хорошее предложение по улучшению? Предложения по улучшению отслеживаются в `GitHub Issues `_. * Используйте **чёткий и описательный заголовок**, чтобы идентифицировать предложение. * Предоставьте **пошаговое и подробное описание** предлагаемого улучшения. * **Опишите текущее поведение** и **объясните, какое вы ожидали увидеть вместо этого** и почему. Здесь же можно указать, какие альтернативы вам не подходят. * **Приложите скриншоты или видео**, которые помогут продемонстрировать шаги или указать на часть, к которой относится предложение. * **Объясните, почему это улучшение будет полезно** большинству пользователей `Argenta`. Вы также можете указать на другие проекты, которые решили эту проблему и могут послужить источником вдохновения. ----- .. _Ваш первый вклад в код: Ваш первый вклад в код ----------------------- Не знаете, с чего начать? Посмотрите на задачи с метками `good first issue` и `help wanted` в нашем репозитории на `GitHub`. Они хорошо подходят для новичков. Чтобы начать, настройте локальное окружение для разработки, следуя этим шагам. #. Сделайте форк репозитория ``Argenta`` на ``GitHub``. #. Клонируйте ваш форк на локальную машину: .. code-block:: bash git clone https://github.com/<ВАШ_НИКНЕЙМ>/Argenta.git cd Argenta #. Создайте и активируйте виртуальное окружение. .. code-block:: bash # Для macOS/Linux python3 -m venv .venv source .venv/bin/activate # Для Windows python -m venv .venv .venv\Scripts\activate #. Установите зависимости проекта, включая инструменты для разработки. .. code-block:: bash pip install -e .[dev] #. Создайте новую ветку для вашей функции или исправления. Используйте описательное имя, например `fix/login-bug` или `feat/new-widget`. .. code-block:: bash git switch -c your-new-branch-name #. Внесите свои изменения. Напишите код и не забудьте добавить или обновить тесты. #. Запустите тесты, чтобы убедиться, что все работает корректно. .. code-block:: bash python -m pytest tests #. Сделайте коммит, следуя нашему руководству по стилю, и отправьте изменения в ваш форк. .. code-block:: bash git add . git commit -m "feat(widget): add the new super widget" git push origin your-new-branch-name #. Откройте `Pull Request` из вашей ветки в ветку `main` официального репозитория. Предоставьте чёткое описание проблемы и вашего решения. Укажите номер связанной задачи, если она есть. ----- .. _Улучшение документации: Улучшение документации ---------------------- Хорошая документация крайне важна. Мы используем `Sphinx` для её генерации из исходных файлов в директории `docs/`. Мы приветствуем любые улучшения: от исправления опечатки до написания нового раздела. .. note:: Мы поддерживаем документацию на двух языках: русском и английском. Для улучшения документации вы можете следовать процессу, похожему на внесение вклада в код: #. Убедитесь, что ваше окружение для разработки настроено, как описано в разделе `Ваш первый вклад в код`_. #. Перейдите в директорию с документацией. .. code-block:: bash cd docs #. Внесите изменения в **русскую** версию документации (`docs/index.rst` и/или `docs/root/*`). #. Чтобы собрать документацию локально и увидеть изменения, выполните: .. code-block:: bash make live-ru #. Откройте `127.0.0.1:8000` в браузере, чтобы просмотреть сгенерированную документацию. #. После завершения работы над русской версией необходимо создать английский перевод: .. code-block:: bash make update-langs #. После обновления шаблона обновите файлы перевода, расположенные в `docs/locales/en/LC_MESSAGES/`. #. Когда изменения будут готовы, сделайте коммит и откройте `Pull Request`. Используйте префикс `docs:` в сообщении коммита. ----- .. _Руководства по стилю: Руководства по стилю -------------------- .. _Сообщения коммитов: Сообщения коммитов ~~~~~~~~~~~~~~~~~~ Мы следуем спецификации `Conventional Commits `_. Это делает историю проекта более читаемой и позволяет автоматически генерировать журнал изменений. Каждое сообщение коммита состоит из **заголовка**, **тела** и **нижнего колонтитула**. .. code-block:: text <тип>(<область>): <тема> [опциональное тело] [опциональный нижний колонтитул] ``<тип>`` должен быть одним из следующих: * **feat**: Новая функция для пользователя. * **fix**: Исправление ошибки для пользователя. * **docs**: Только изменения в документации. * **style**: Изменения, не влияющие на смысл кода (пробелы, форматирование и т.д.). * **refactor**: Изменение кода, которое не исправляет ошибку и не добавляет новую функцию. * **perf**: Изменение кода, улучшающее производительность. * **test**: Добавление недостающих тестов или исправление существующих. * **chore**: Изменения в процессе сборки или вспомогательных инструментах и библиотеках. .. rubric:: Примеры Простое исправление: ``fix: correct typo in user authentication flow`` Новая функция с областью видимости: ``feat(api): add new endpoint for user profiles`` ----- .. _Присоединяйтесь к команде проекта: Присоединяйтесь к команде проекта --------------------------------- Мы всегда ищем энтузиастов для присоединения к команде. Если вы являетесь постоянным участником и продемонстрировали глубокое понимание целей и архитектуры проекта, вы можете стать хорошим кандидатом на роль мейнтейнера. Активные члены сообщества могут стать членами команды. Обычно это включает: * Постоянный вклад в виде качественного кода и документации. * Помощь другим пользователям с их вопросами и проблемами. * Проверку `Pull Request`'ов от других участников с конструктивной обратной связью. Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ — быть активным и полезным участником сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами.