.. _root_contributing: Вклад в проект ============== .. default-role:: code Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️ Мы приветствуем и ценим любые виды вклада. Пожалуйста, прочтите соответствующий раздел, прежде чем делать свой вклад. Это значительно облегчит работу для нас, мейнтейнеров, и сделает процесс более гладким для всех участников. Сообщество с нетерпением ждет ваших вкладов. 🎉 .. note:: Если вам нравится проект, но у вас просто нет времени на вклад, это нормально. Есть и другие простые способы поддержать проект и выразить свою признательность, которым мы также будем очень рады: * Поставить звезду проекту * Написать о нем в ``Twitter`` * Ссылаться на этот проект в `Readme` вашего проекта * Упомянуть проект на местных встречах и рассказать о нем друзьям/коллегам .. _Содержание: Содержание ---------- * `Кодекс поведения`_ * `У меня есть вопрос`_ * `Я хочу внести вклад`_ * `Сообщение об ошибках`_ * `Предложение улучшений`_ * `Ваш первый вклад в код`_ * `Улучшение документации`_ * `Руководства по стилю`_ * `Сообщения коммитов`_ * `Присоединяйтесь к команде проекта`_ .. _Кодекс поведения: Кодекс поведения ---------------- Этот проект и все его участники руководствуются :ref:`Кодексом поведения Argenta `. Участвуя, вы обязуетесь соблюдать этот кодекс. Пожалуйста, сообщайте о недопустимом поведении. ----- .. _У меня есть вопрос: У меня есть вопрос ------------------ .. note:: Если вы хотите задать вопрос, мы предполагаем, что вы уже ознакомились с доступной `Документацией `_. Прежде чем задать вопрос, лучше всего поискать существующие `Issue `_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете. Если после этого вы все еще чувствуете необходимость задать вопрос, мы рекомендуем следующее: * Откройте новый `Issue `_. * Предоставьте как можно больше контекста о том, с чем вы столкнулись. * Укажите версии проекта и платформы (cpython, pip и т.д.), в зависимости от того, что кажется релевантным. Мы займемся вашей задачей как можно скорее. ----- .. _Я хочу внести вклад: Я хочу внести вклад ------------------- .. rubric:: Правовое уведомление .. note:: Внося вклад в этот проект, вы должны согласиться с тем, что вы являетесь автором 100% контента, что у вас есть необходимые права на этот контент, и что предоставленный вами контент может распространяться под лицензией проекта. .. _Сообщение об ошибках: Сообщение об ошибках -------------------- .. rubric:: Перед отправкой отчета об ошибке Хороший отчет об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Поэтому мы просим вас тщательно все изучить, собрать информацию и подробно описать проблему в своем отчете. Пожалуйста, выполните следующие шаги заранее, чтобы помочь нам исправить любую потенциальную ошибку как можно быстрее. * Убедитесь, что вы используете последнюю версию. * Определите, действительно ли ваша проблема является ошибкой, а не ошибкой с вашей стороны, например, из-за использования несовместимых компонентов/версий окружения (Убедитесь, что вы прочитали `документацию `_. Если вам нужна поддержка, возможно, стоит заглянуть в раздел `У меня есть вопрос`_). * Чтобы увидеть, сталкивались ли другие пользователи (и, возможно, уже решили) с той же проблемой, проверьте, нет ли уже отчета о вашей ошибке в `трекере ошибок `_. * Также обязательно поищите в интернете (включая ``Stack Overflow``), чтобы узнать, обсуждали ли проблему пользователи за пределами сообщества ``GitHub``. * Соберите информацию об ошибке: * Трассировка стека * ОС, платформа и версия ``Windows``, ``Linux``, ``macOS``, ``x86``, ``ARM`` * Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов, в зависимости от того, что кажется релевантным. * Возможно, ваши входные данные и результат * Можете ли вы надежно воспроизвести проблему? И можете ли вы воспроизвести ее на старых версиях? .. rubric:: Как мне отправить хороший отчет об ошибке? .. note:: Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках, содержащих конфиденциальную информацию, в трекере задач или в других публичных местах. Конфиденциальные ошибки должны быть отправлены по электронной почте. Мы используем ``Issues GitHub`` для отслеживания ошибок. Если вы столкнулись с проблемой в проекте: * Откройте `Issue `_. (Поскольку на данном этапе мы не можем быть уверены, является ли это ошибкой, мы просим вас пока не говорить об ошибке и не присваивать метку задаче.) * Объясните поведение, которое вы ожидали, и фактическое поведение. * Пожалуйста, предоставьте как можно больше контекста и опишите *шаги для воспроизведения*, чтобы кто-то другой мог воссоздать проблему самостоятельно. Обычно это включает ваш код. Для хороших отчетов об ошибках следует изолировать проблему и создать сокращенный тестовый пример. * Предоставьте информацию, которую вы собрали в предыдущем разделе. После того, как задача будет создана: * Команда проекта присвоит задаче соответствующую метку. * Член команды попытается воспроизвести проблему по вашим шагам. Если шагов для воспроизведения нет или нет очевидного способа воспроизвести проблему, команда попросит вас предоставить эти шаги и пометит задачу как `needs-repro`. Ошибки с меткой `needs-repro` не будут рассматриваться до тех пор, пока они не будут воспроизведены. * Если команда сможет воспроизвести проблему, она будет помечена как `needs-fix`, а также, возможно, другими метками (например, `critical`), и задача будет оставлена для :ref:`реализации кем-либо <Ваш первый вклад в код>`. ----- .. _Предложение улучшений: Предложение улучшений --------------------- Этот раздел поможет вам отправить предложение по улучшению ``Argenta``, **включая совершенно новые функции и незначительные улучшения существующей функциональности**. Следование этим рекомендациям поможет мейнтейнерам и сообществу понять ваше предложение и найти связанные с ним предложения. .. rubric:: Перед отправкой предложения по улучшению * Убедитесь, что вы используете последнюю версию. * Внимательно прочтите `документацию `_ и выясните, не реализована ли уже данная функциональность, возможно, через индивидуальную конфигурацию. * Выполните `поиск `_, чтобы проверить, не было ли уже предложено данное улучшение. Если да, добавьте комментарий к существующей задаче вместо создания новой. * Определите, соответствует ли ваша идея масштабам и целям проекта. Вам предстоит убедительно доказать разработчикам проекта достоинства этой функции. Помните, что мы хотим видеть функции, которые будут полезны большинству наших пользователей, а не только небольшой их части. Если вы ориентируетесь только на меньшинство пользователей, рассмотрите возможность написания дополнения/плагина. .. rubric:: Как мне отправить хорошее предложение по улучшению? Предложения по улучшению отслеживаются как `Issues GitHub `_. * Используйте **четкий и описательный заголовок** для задачи, чтобы идентифицировать предложение. * Предоставьте **пошаговое описание предлагаемого улучшения** как можно подробнее. * **Опишите текущее поведение** и **объясните, какое поведение вы ожидали увидеть вместо этого** и почему. На этом этапе вы также можете указать, какие альтернативы вам не подходят. * Вы можете **включить скриншоты или записи экрана**, которые помогут продемонстрировать шаги или указать на часть, к которой относится предложение. * **Объясните, почему это улучшение было бы полезно** большинству пользователей ``Argenta``. Вы также можете указать на другие проекты, которые решили эту проблему лучше и которые могут послужить источником вдохновения. ----- .. _Ваш первый вклад в код: Ваш первый вклад в код ----------------------- Не знаете, с чего начать свой вклад в ``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`` официального репозитория ``Argenta``. Предоставьте четкое описание проблемы и вашего решения. Укажите номер связанной задачи, если это применимо. ----- .. _Улучшение документации: Улучшение документации ---------------------- Хорошая документация крайне важна для любого проекта. Мы используем ``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`` от других участников с конструктивной обратной связью. Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ начать — это быть активным и полезным членом сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами с приглашением присоединиться к команде.