Безопасное и автоматическое обновление ReadMe

Привет, Хабр. Сегодня я расскажу о своей попытке сделать автоматическое обновление версии библиотеки в ReadMe. Это моя первая статья. (Старался писать коротко и не делать просто перевод ReadMe). Все что я описываю в данной статье обсудили в подкасте Android Story выпуск 7.


Проблема


Предположим, что имеется некоторый абстрактный разработчик (я), который любит писать свои маленькие библиотеки. По каждой библиотеки необходимо написать ReadMe. Нас интересует часть, где мы показываем как подключить наш чудо проект.


Как правило, это что-то из следующего:


  • Добавить нашу чудо библиотеку в gradle / maven / ant dependencies
  • … (Другой способ подключить что-то с какого центрального хранилища)

Решение


На данный момент на GitHub я видел два решения. Если автор ленивый то в ReadMe мы видим {current version}/ {last version}. И далее для любого, кто хочет подключить данную библиотеку начинается квест под названием "найди последнего версию библиотеки". Если автор не ленивый или просто хочет максимально спороститы жизнь разработчикам, которые используют библиотеку, то после каждого релиза автор правит ReadMe руками.


Мое решение


Обвинять автора библиотеки в том, что он ленивый мы конечно не будем, потому что лень — это двигатель прогресса. Мы просто сделаем автоматизацию. Здесь надо написать список требований к нашему сервису


  1. Простая интеграция.
  2. Не требует никаких доступов.
  3. Не собирает данных.

(Спойлер: это все реально. На самом деле, многие сервисы, которые сейчас требуют доступ к репозитория могут обойтись без него)




Если вам не интересно как это работает под капотом, тогда просто подключайте GoodReadMeAction.


Если вам не интересны детали реализации сервиса, но вы хотите его развернуть self-host, то:



Как это работает?


Общий алгоритм работы сервиса


Сделать Fork -> Обновить ReadMe -> сделать Pull request.


Для простоты работы с GitHub я создал аккаунт, от имени которого сервис выполняет все действия. С стороны GitHub наш сервис это просто юзер который делать Pull request в репозитории. (Только с поправкой на то, что наш пользователь все делать через API).


Как сервис узнает о новых релизы?


Здесь я сделал два варианта подключения:


  1. Добавить себе GoodReadMeAction, который запускается когда создается новый release и вызывает сервис через API. Рекомендую имено это способ, так как он не отправляет лишних ивентов на сервер.
  2. WebHook инструкция по подключению

Алгоритм обновления ReadMe


Через GitHub API вытаскиваем список релизов. Находим Последние два которые не pre-release и не черновики. В соответствии получаем предыдущий и актуальный релиз. В ReadMe во всех блоках кода(которые в markdown видилються ```) делаем замену названия предыдущего релиза на название актуального.


Детали работы с GitHub


Actions fail


В первой версии сервис удалял Fork сразу после создания PR. GitHub actions не были готовы к такому. Так как source для PR был unknow repository. На экране PR пишет что ожидается статус окончания Actions. А если открыть Actions видим что Action упал с неизвестной ошибкой и силки на службу поддержки GitHub. (В поддержку написал, но пока ничего не известно). Поэтому данная версия не могла использоваться в репозиториях где используется Actions для проверки PR. Проблему решил на своей стороне. Удаляем fork перед тем как делать новый fork, а не после того как сделали PR.


Token


Просто интересный факт, в случае если вы захаркодете GitHub token в репозиторий то GitHub автоматически отзовет его.


Место для вывода


Быть ленивым круто, потому что


Силки


Подкаст
Мой github action

Tags:
open source, ReadMe, kotlin, ktor,

You can't comment this post because its author is not yet a full member of the community. You will be able to contact the author only after he or she has been invited by someone in the community. Until then, author's username will be hidden by an alias.