Публикация и CI

Совсем немного про CI

Непрерывная_интеграция:

• получение исходного кода из репозитория;
• сборка проекта;
• выполнение тестов;
• развёртывание готового проекта;
• отправка отчетов.

Обратите внимание: сборка проекта. Как следствие, инструменты сборки утекли с локальной машины на CI-платформу:

• Возможность собирать под любую платформу

• Возможность проводить полноценный деплоймент

Как следствие, «умные» инструменты автоматизации сборки типа Make уступили место простым очередям заданий

• https://travis-ci.com

• https://github.com/features/actions

  • синтаксис файла с описанием

• https://docs.gitlab.com/ee/ci/

  • В GitLab начали задумываться над графом зависимостей, но как-то очень путано

• … (тысячи их)

Пример проекта на GitHub

Довольно извращённый модуль: Словарь с тегами

• Используется GH Actions
  • Развертывание виртуальной машины с указанной ОС
  • Установка пакетов в ОС
  • Собственно действия — запуск команд shell
    • Дополнительная настройка (например, pip install)
    • Собственно тестирование / сборка / и т. п.

• Сценарий (т. н. manifest) с описанием всего этого

• Манифест может активизироваться вручную или по событию (например, просто при каждом push, на каждый новый тег, только на подписанный тег и т. п.).
• Могут получаться т. н. «артефакты», их можно публиковать
• Результаты любого действия могут быть оформлены в виде «бейджиков» в любом HTML (включая README.md)

…

Публикация на PyPi

В действительности ничего свыше методички на PyPA не требуется:

• Необходимо создать исходный и бинарный дистрибутивы со всеми нужными полями в заголовке, лицензией и т. п.

• Публикация происходит с помощью специального инструмента — twine

  • Вместо логина надо указывать слово __token__, вместо пароля — выданный вам ключ.

  • Этот же ключ могут использовать и роботы CI, но очень важно не пропалить его!

  • Можно использовать $HOME/.pypirc

• Немедленно после успешной публикации модуль можно устанавливать!

• на PyPI нельзя выкладывать файл с одним и тем же именем повторно, даже если вы вообще удалили и завели заново соответствующий проект. Если хоть что-то поменяли — поднимайте номер версии.

• README.md из дистрибутива можно использовать в качестве описания проекта, а вот другие файлы (например, картинки) — нет. Однако можно сослаться readthedocs.io!

(если успеем) Пробная публикация на test.pypi.org

TODO

Проблема версионирования

Классический релиз менеждмент с тегами (например, на GitHub vs version =  в pyproject.toml — синхронизация номера версии?

• когда был setup.py, решалась гененрацией версии

• В pyproject.toml решена отказом от декларативности (секция project.dynamic)

  • Есть 100500 вариантов

  • В taggedict используется setuptools-git-versioning

• может быть решена высокоуровневыми инструментами типа Poetry

Кстати, о принципах версионирования:

• Semantic Versioning

• версионирование библиотек от GNU

Публикация на readthedocs.io

Тут всё ещё проще! Достаточно, чтобы в вашем проекте выгонялась документация с помощью sphinx.

• Залогиниться и указать репозиторий, из которого будет произведён экспорт
• Документация будет пересоздана создана автоматически на база исходного репозитория (самому генерировать её не надо)

• Если код написан так, что при выгонке документации требуется импортировать внешние модули, возможны ошибки (это тоже своего рода CI, но никто не будет ставить, допустим, matplotlib). Не забывайте про -autodoc_mock_imports!

• Такую публикацию можно тоже подключить в CI

  • + readthedocs.io сам умеет следить за тегами!

• Пример для taggedict

• Пример для эталонного пректа

Foreword

1. Нельзя объять необъятного!
2. Изучение конкретных инструментариев — долгий, не не очень сложный процесс, поэтому мы ограничились простыми случаями

3. Всегда следите за обновлениями Python — они не очень большие

4. Сначала гуглите и пробуйте, а только потом изобретайте сами
5. Доводите проекты до публикации в PyPI
6. Если хотите, чтобы вам кто-то помог — организуйте [[удобное информационное пространство
   • Дисциплину оформления коммитов
   • Документацию
   • Дисциплину оформления тестов и контроль покрытия
   • Дисциплину приёма pull-реквестов

   • Например, так (в GH есть напоминалка «Community standards)

7. …