contributing.md

contributing

issue

• если увидели открытый issue и готовы им заняться, отпишите что берете на себя и сколько потребуется предварительно времени
• если хотите добавить что-то новое, следует начать с создания issue и описания

pull request

• создайте fork и клонируйте репозиторий
• создайте новую ветку (к примеру, git checkout -b issue-id-short-name)
• изменяйте/добавляйте что нужно
• push
• pull request
• ожидайте комментариев от команды курса

если состоите в какой-нибудь из команд курса, то начинайте со 2 шага

pre-commit

как часть непрерывной интеграции (ci)

• установить pre-commit

  pip install pre-commit
  

• запустить

  pre-commit run -a
  

после чего, автоматически произойдёт запуск указанных в .pre-commit-config.yaml библиотек где часть автоматически изменит что нужно (добавить пустую строку в конце), а остальная с ошибкой подскажет что требуется править. для проверки всё ли нормально смело можете запускать сколько потребуется раз

добавить лекцию

все лекции лежат в ./docs/ в соответствующих директориях

всё содержание книги находится в ./mkdocs.yml по ключу nav

картинки и иже находятся в _static/ в нужном разделе/вкладке (к примеру, в ./docs/base/ – «основы python» – не более)

авторство

если была создана лекция и/или любое иное важное улучшение, то смело добавляйте себя в неё и в общий список авторов курса

окружение/среда

курс разрабатывается на движке mkdocs

собрать промежуточную версию книги

gh actions (для членов команды курса)

• перейти во вкладку actions и выбрать cd-stage процесс
• справа в таблице в выпадающем меню run workflow выбрать нужную ветку и нажать зелёную кнопку запуска
• после пары минут по адресу pycourse-page-stage.netlify.app можно лицезреть собранную книгу

локально

• клонировать нужную ветку (или fork)

• установить нужные библиотеки (лучше в отдельном виртуальном окружении)

  pip install -r requirements.txt
  

• запустить

  mkdocs serve --dirtyreload
  

• перейти по предложенной внутренней ссылке, дабы открыть книгу

стилистика

на странице движка – https://squidfunk.github.io/mkdocs-material/reference/ – имеются примеры (sponsors only не наш случай) как можно во всю его использовать, не ограничивайте себя, главное чтобы было понятно даже школьнику

меж тем

• вместо – использовать – (option + - для macos)
• рисунки в .png формате
• примеры кода всегда содержат нумерацию строк
• "" в коде
• «» в простом тексте
• лучше не использовать «мы»/«вы»/«вас»/«нас»/..
• ..