Простой способ для команд просматривать блокноты Jupyter на GitHub.

В ReviewNB мы уже поддерживаем визуальные различия и обзоры блокнотов Jupyter для коммитов/реквестов GitHub.

Сегодня мы выпускаем JDoc, простой способ для команд просматривать записные книжки на GitHub. Вы можете открыть записную книжку в своем репозитории и начать обсуждение в любой ячейке записной книжки. Товарищи по команде, просматривающие этот репозиторий или участвующие в беседе, будут уведомлены (по электронной почте), чтобы они могли присоединиться и продолжить беседу. Этот рабочий процесс был бы очень полезен для команд Data Science / ML, чтобы проверять работу друг друга, задавать уточняющие вопросы и оставлять отзывы прямо в ячейке блокнота.

Почему новая функция?

Мы предлагаем функцию просмотра записной книжки по запросу на вытягивание, которая отлично работает во многих случаях, но в некоторых не работает.

  • Иногда различия в блокнотах не важны. Например. Я записал новую записную книжку с некоторым специальным анализом и хотел бы, чтобы кто-то из моей команды проверил ее. Создание запроса на вытягивание для проверки немного излишне, так как для этого файла нет различий (недавно добавленный блокнот) и нет рабочего процесса merge-to-master после проверки (специальный анализ).
  • Не все пользователи записных книжек хорошо разбираются в Git/GitHub. Просить их создавать ветки функций и открывать пулреквесты может быть слишком сложно. С JDoc автору просто нужно зафиксировать блокнот на GitHub, и он будет доступен для просмотра.
  • Иногда вам нужно просмотреть все прошлые обсуждения в определенной записной книжке и перейти к другой версии файла. JDoc упрощает эту задачу благодаря ориентированному на ноутбуки подходу к рецензированию и контролю версий.

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

  • Когда вы открываете репозиторий на ReviewNB, теперь вы видите новую вкладку NOTEBOOKS.

  • Вы можете открыть блокнот и начать разговор в любой ячейке блокнота

  • Товарищи по команде, просматривающие этот репозиторий или участвующие в беседе, получат уведомление о новом комментарии по электронной почте. Конечно, они могут отписаться от уведомлений по электронной почте, если они того пожелают.
  • Товарищи по команде могут ответить/разрешить/начать новый разговор или просто просмотреть комментарии. Также есть вкладка ИЗМЕНЕНИЯ, на которой показана история версий этого блокнота.

Важные вещи, на которые следует обратить внимание

  • При проверке запросов на вытягивание все комментарии, которые вы пишете на ReviewNB, напрямую публикуются в соответствующем PR на GitHub. При использовании JDoc все комментарии, которые вы пишете, сохраняются в ReviewNB. Это связано с тем, что GitHub не предлагает никакого способа публиковать комментарии непосредственно в файле (комментарии GitHub разрешены только для коммитов/PR). Конечно, ваши комментарии в безопасности с ReviewNB, и администраторы репозитория могут запросить машиночитаемый экспорт всех комментариев в своем репозитории.
  • В настоящее время если вы измените имя/путь блокнота в репозитории, он будет рассматриваться как новый файл, и вы не увидите в нем старые беседы. Это связано с тем, что нелегко обнаружить переименование файлов с необработанными данными git. В будущем мы предоставим пользовательский интерфейс для указания переименований, которые затем будут переноситься поверх комментариев.
  • Поскольку JDoc похож на Google Docs для Jupyter, за всю жизнь блокнота может накопиться множество разговоров. Было бы разумно активно разрешать/удалять старые разговоры, чтобы сохранить документ в чистоте и порядке.

Вывод

JDoc снижает входной барьер для экспертных оценок Jupyter Notebooks. И в некоторых случаях они имеют больше смысла, чем проверка запросов на вытягивание, например. вы хотите просмотреть только что добавленный блокнот или просто хотите разместить окончательную версию блокнота для проверки и не заботитесь о дополнительных обновлениях, чтобы получить ее.

Обзоры запросов на слияние по-прежнему хороши тем, что позволяют увидеть визуальные различия и служат фантастическим контейнером для обсуждения. В процессе PR также присутствует инженерная строгость, поскольку конечным результатом является слияние с мастером.

Я надеюсь, что вы сможете объединить силу PR-обзоров и гибкость JDoc, чтобы достичь баланса, подходящего для вашей команды.

Удачного взлома!

Первоначально опубликовано на https://blog.reviewnb.com 20 июня 2020 г.