mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
299 lines
19 KiB
ReStructuredText
299 lines
19 KiB
ReStructuredText
.. _root_contributing:
|
||
|
||
Вклад в проект
|
||
==============
|
||
|
||
.. default-role:: code
|
||
|
||
Прежде всего, спасибо, что уделили время для внесения своего вклада! ❤️
|
||
|
||
Мы приветствуем и ценим любой вклад. Пожалуйста, прочтите соответствующий раздел, прежде чем начать. Это облегчит работу мейнтейнеров и сделает процесс более гладким для всех. Сообщество с нетерпением ждёт ваших идей! 🎉
|
||
|
||
.. note::
|
||
|
||
Если вам нравится проект, но у вас нет времени на активный вклад, вы можете поддержать нас другими способами:
|
||
|
||
* Поставить звезду на GitHub.
|
||
* Написать о проекте в Twitter или других социальных сетях.
|
||
* Сослаться на проект в `README` вашего репозитория.
|
||
* Упомянуть проект на митапах и рассказать о нём друзьям и коллегам.
|
||
|
||
.. _Содержание:
|
||
|
||
Содержание
|
||
----------
|
||
|
||
* `Кодекс поведения`_
|
||
* `У меня есть вопрос`_
|
||
* `Я хочу внести вклад`_
|
||
* `Сообщение об ошибках`_
|
||
* `Предложение улучшений`_
|
||
* `Ваш первый вклад в код`_
|
||
* `Улучшение документации`_
|
||
* `Руководства по стилю`_
|
||
* `Сообщения коммитов`_
|
||
* `Присоединяйтесь к команде проекта`_
|
||
|
||
.. _Кодекс поведения:
|
||
|
||
Кодекс поведения
|
||
----------------
|
||
|
||
Этот проект и все его участники руководствуются :ref:`Кодексом поведения Argenta <root_code_of_conduct>`.
|
||
Участвуя, вы обязуетесь соблюдать этот кодекс. Пожалуйста, сообщайте о недопустимом поведении.
|
||
|
||
-----
|
||
|
||
.. _У меня есть вопрос:
|
||
|
||
У меня есть вопрос
|
||
------------------
|
||
|
||
.. note::
|
||
|
||
Прежде чем задать вопрос, пожалуйста, ознакомьтесь с `документацией <https://argenta.readthedocs.io>`_.
|
||
|
||
Поищите ответ в существующих `Issues <https://github.com/koloideal/Argenta/issues>`_. Если вы нашли похожий вопрос, но всё ещё нуждаетесь в разъяснениях, можете написать в нём. Также рекомендуем поискать ответ в интернете.
|
||
|
||
Если ответа не нашлось, создайте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_ и предоставьте как можно больше контекста, включая версии проекта и платформы (CPython, pip и т.д.).
|
||
|
||
Мы займемся вашей задачей как можно скорее.
|
||
|
||
-----
|
||
|
||
.. _Я хочу внести вклад:
|
||
|
||
Я хочу внести вклад
|
||
-------------------
|
||
|
||
.. rubric:: Правовое уведомление
|
||
|
||
.. note::
|
||
|
||
Внося вклад в этот проект, вы подтверждаете, что являетесь автором 100% контента, обладаете необходимыми правами на него и соглашаетесь, что он может распространяться под лицензией проекта.
|
||
|
||
.. _Сообщение об ошибках:
|
||
|
||
Сообщение об ошибках
|
||
--------------------
|
||
|
||
.. rubric:: Перед отправкой отчета об ошибке
|
||
|
||
Хороший отчёт об ошибке не должен заставлять других вытягивать из вас дополнительную информацию. Пожалуйста, тщательно всё изучите, соберите информацию и подробно опишите проблему. Это поможет нам исправить её как можно быстрее.
|
||
|
||
* Убедитесь, что вы используете последнюю версию.
|
||
* Убедитесь, что проблема действительно является ошибкой, а не вызвана, например, использованием несовместимых версий окружения. Прочтите `документацию <https://argenta.readthedocs.io>`_ и, если нужна поддержка, загляните в раздел `У меня есть вопрос`_.
|
||
* Проверьте, нет ли уже отчёта о вашей ошибке в `трекере <https://github.com/koloideal/Argenta/issues?q=label%3Abug>`_.
|
||
* Также поищите в интернете (включая `Stack Overflow`), чтобы узнать, обсуждалась ли проблема за пределами `GitHub`.
|
||
* Соберите информацию об ошибке:
|
||
* Трассировка стека.
|
||
* ОС, платформа и версия (Windows, Linux, macOS, x86, ARM).
|
||
* Версия интерпретатора, компилятора, SDK, среды выполнения, менеджера пакетов и т.д.
|
||
* Входные данные и полученный результат.
|
||
* Можете ли вы надёжно воспроизвести проблему? Воспроизводится ли она на старых версиях?
|
||
|
||
.. rubric:: Как мне отправить хороший отчет об ошибке?
|
||
|
||
.. note::
|
||
|
||
Никогда не сообщайте о проблемах безопасности, уязвимостях или ошибках с конфиденциальной информацией в публичном трекере. Для этого используйте электронную почту.
|
||
|
||
Мы используем `GitHub Issues` для отслеживания ошибок. Если вы столкнулись с проблемой:
|
||
|
||
* Откройте новый `Issue <https://github.com/koloideal/Argenta/issues/new>`_. На этом этапе не нужно присваивать ему метки.
|
||
* Объясните ожидаемое и фактическое поведение.
|
||
* Предоставьте как можно больше контекста и опишите **шаги для воспроизведения**, чтобы проблему можно было воссоздать. Лучше всего изолировать её и создать минимальный тестовый пример.
|
||
* Предоставьте информацию, которую вы собрали в предыдущем разделе.
|
||
|
||
После того, как задача будет создана:
|
||
|
||
* Команда проекта присвоит задаче соответствующую метку.
|
||
* Член команды попытается воспроизвести проблему. Если шагов нет или они не приводят к результату, команда попросит вас предоставить их и пометит задачу как `needs-repro`. Такие задачи не будут рассматриваться до тех пор, пока проблема не будет воспроизведена.
|
||
* Если проблема будет воспроизведена, она будет помечена как `needs-fix` (и, возможно, другими метками, например `critical`), после чего её сможет взять в работу :ref:`любой желающий <Ваш первый вклад в код>`.
|
||
|
||
-----
|
||
|
||
.. _Предложение улучшений:
|
||
|
||
Предложение улучшений
|
||
---------------------
|
||
|
||
Этот раздел поможет вам отправить предложение по улучшению `Argenta`, **включая как новые функции, так и незначительные улучшения**. Следование этим рекомендациям поможет мейнтейнерам и сообществу лучше понять вашу идею.
|
||
|
||
.. rubric:: Перед отправкой предложения по улучшению
|
||
|
||
* Убедитесь, что вы используете последнюю версию.
|
||
* Внимательно прочтите `документацию <https://argenta.readthedocs.io>`_ и убедитесь, что предлагаемая функциональность ещё не реализована (возможно, через конфигурацию).
|
||
* Выполните `поиск <https://github.com/koloideal/Argenta/issues>`_, чтобы проверить, не предлагалось ли это улучшение ранее. Если да, добавьте комментарий к существующей задаче.
|
||
* Определите, соответствует ли ваша идея масштабу и целям проекта. Вам предстоит убедительно доказать её пользу. Мы хотим видеть функции, которые будут полезны большинству пользователей. Если ваша идея ориентирована на узкий круг, рассмотрите возможность создания плагина.
|
||
|
||
.. rubric:: Как мне отправить хорошее предложение по улучшению?
|
||
|
||
Предложения по улучшению отслеживаются в `GitHub Issues <https://github.com/koloideal/Argenta/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 <https://www.conventionalcommits.org/en/v1.0.0/>`_. Это делает историю проекта более читаемой и позволяет автоматически генерировать журнал изменений.
|
||
|
||
Каждое сообщение коммита состоит из **заголовка**, **тела** и **нижнего колонтитула**.
|
||
|
||
.. 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`'ов от других участников с конструктивной обратной связью.
|
||
|
||
Если вы заинтересованы в том, чтобы стать постоянным членом команды, лучший способ — быть активным и полезным участником сообщества. Существующие мейнтейнеры заметят ваши усилия и могут связаться с вами.
|
||
|