Skip to content

Latest commit

 

History

History
142 lines (104 loc) · 9.12 KB

CONTRIBUTING.md

File metadata and controls

142 lines (104 loc) · 9.12 KB
Raw

Коллективное участие в проекте

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

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

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

Стиль

В курсе используются следующие стандарт кодирования:

Рекомендуется добавлять аннотации типов, используя стандарты:

Для проверки вашего кода на соответствие стилю предлагается файл конфигурации .pylintrc для pylint, расположенный в корневом каталоге проекта.

Вы можете проверить свои файлы с помощью следующей команды:

python -m pylint --rcfile=.pylintrc path_to_file

Стиль строк документации Python

Строки документации в коде на Python рекомендуется оформлять по следующим стандартам:

Следует придерживаться стиля Sphinx, который использует разметку reStructuredText:

Тестирование

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

Перед создание pull request убедитесь, что 100% Вашего кода покрыто тестами.

Для запуска тестов Вы можете использовать команду:

python -m unittest path_to_file_with_tests

Сообщения коммитов

  • Ограничьте первую строку 72 символами или меньше
  • Подумайте о том, чтобы начать сообщение с подходящего эмодзи:
    • 🎨 :art: при добавлении изображений/улучшении оформления
    • 📝 :memo: при добавлении/изменении сопутствующих текстовых файлов
    • 📌 :pushpin: при добавлении сопутствующих файлов конфигураций и др.
    • 🐍 :snake: при добавлении/изменении кода
    • ✏️ :pencil2: при добавлении нового задания
    • 🐛 :bug: при исправлении ошибки
    • 💚 :green_heart: при исправлении сборки CI/CD
    • 🧪 :test_tube: при добавлении тестов

Как я могу внести свой склад?

Сообщить об ошибке

В этом разделе представлены инструкции по отправке отчета об ошибке для CyberGrowBox. Следование этим рекомендациям помогает специалистам по сопровождению и сообществу понять ваш отчет 📋 и воспроизвести поведение 💻.

Если вы нашли ошибку не стесняйтесь сообщить об этом.

Чтобы сообщить об ошибке придерживайтесь следующих простых правил 📝:

  • Проверьте раздел issues, чтобы не создавать дубликатов
  • Задайте понятный заголовок issues, лаконично и исчерпывающе определяющий проблему
    • постарайтесь не допускать двойного смысла, сленга и т.д.
  • Опишите сценарий воспроизведения ошибки или место в тексте, где она присутствует
    • скриншоты очень сильно помогают, но не заменяют сценарий
    • добавьте сообщение об ошибке (если это связано с кодом)
  • Опишите в чем заключается ошибка по вашему мнению
  • Опишите ожидаемое поведение или представление

Добавление нового алгоритма

  • Сделайте pull request конкретным и целенаправленным. Вместо того, чтобы вносить «несколько алгоритмов сортировки» одновременно, добавьте их все по одному по отдельности (т.е. один pull request для «быстрой сортировки», другой для «сортировки кучей» и т. д.).
  • Задавайте понятный заголовок pull request, лаконично и исчерпывающе определяющий новй алгоритм (возможно указать название алгоритма).
  • Предоставьте README.md для каждого из алгоритмов с объяснениями алгоритма и ссылками на дополнительные материалы.
  • Сопроводите Ваш код комментариями, отражающими Ваши действия и тонкости реализации.
  • Добавьте несколько примеров работы алгоритма в функции main.

Добавление нового задания

  • Сделайте pull request для каждого задания по отдельности.
  • Задавайте понятный заголовок pull request, лаконично и исчерпывающе определяющий задание.
  • Оформите задание в файле practice_a.b.mb, где a и b порядкова нумерация.
  • Следуйте структуре аналогичных файлов с заданиями.
  • Добавьте несколько тестов, обеспечивающих проверку правильности выполнения задания.

Добавление новых ссылок

Для внесения предложения по улучшению курса следуйте простым шагам:

  • Задайте понятный заголовок issue, лаконично и исчерпывающе определяющий Ваше предложение.
  • Укажите, что вы предлагаете: новую книгу, канал, видео, ссылку и др.
  • Опишите суть предложения и обсудите в issue необходимость добавления нового ресурса.
  • Реализуйте Ваше предложение и предложите его через Pull request.

Добавление нового перевода

Вы можете выполнить перевод любых файлов с описанием. Создайте новый файл README.xx-XX.md или practice_a.b.xx-XX.mb с переводом вместе с основным файлом README.md или practice_a.b.mb, где xx-XX - это языковой стандарт и коды страны/региона. Например en-US, zh-CN, zh-TW, ko-KR и т. Д.