Как мы создали наше приложение для GitHub

Приложение Swimm для GitHub помогает командам разработчиков создавать, поддерживать и находить документацию в рамках рабочего процесса разработки.

Когда наша команда в Swimm начала разрабатывать приложение Swimm для GitHub, нам нужно было определить наилучший момент для взаимодействия с пользователями. Например, мы знали, что запуск и уведомление пользователей о каждой открытой ветке может раздражать, и мы хотели сделать этот процесс простым и приятным. Более того, мы понимали, что должны найти окно возможностей для разработчиков — лучшее время, когда инженеры-программисты ищут проверки, обзоры и комментарии.

Дизайн приложения Swimm для GitHub

Наша команда Swimm начала разработку интеграции приложения GitHub в 2021 году, помня о том, что большинство взаимодействий происходит во время Pull Requests, потому что это обычно последняя точка, где код может быть проверен до того, как он будет объединен в основную ветку и развернут. Но это также первый момент, когда инженеры-программисты выкладывают свой код и отмечают его как готовый к рассмотрению.

В первоначальной версии приложения Swimm для GitHub App наша проверка Swimm Verify выполнялась всякий раз, когда открывался PR или обновлялся открытый PR. Это позволило нам убедиться, что документация в ветке остается актуальной, так что изменения кода не потребуют обновления документации.

Постоянное совершенствование приложения Swimm для GitHub

С тех пор мы добавили довольно много возможностей и функций. Сегодня мы расскажем о возможностях приложения Swimm’s GitHub по порядку.

Принятие изменений с автосинхронизацией из GitHub

Запатентованный алгоритм автосинхронизации Swimm анализирует то, что происходит в вашей кодовой базе. Когда проверка Swimm Verify распознает изменения документации Auto-sync, пользователи получают уведомление через комментарий к вашему pull request. Затем вы можете инициировать Swimm Commit, нажав на кнопку «Approve Auto-sync» в проверке, которая принимает все Auto-synced docs из приложения GitHub.

Автоматическое одобрение автосинхронизации

Мы продвинули функцию автосинхронизации еще на один шаг вперед. В настройках приложения GitHub вы можете установить автоматическое утверждение Auto-sync. Приложение Swimm для GitHub будет автоматически принимать изменения с автосинхронизацией, фиксируя их в вашем открытом запросе на вытягивание в специальном коммите. Клиенты полагаются на надежный запатентованный алгоритм Auto-sync компании Swimm для автоматического обновления документации с помощью этой функции.

Уведомления о новых документах

Поскольку отслеживание и поиск документации является сложной задачей, мы разработали функцию уведомлений о новых документах: вы можете установить оповещение в Slack или по электронной почте всякий раз, когда создается новый документ и сливается с вашей основной веткой. Это поможет отслеживать новую документацию в вашем репозитории и позволит вам пригласить других членов вашей организации прочитать и узнать больше о новой документации. Мы обнаружили, что это способствует лучшему общему пониманию кодовой базы.

Черновые документы из заявок на поставку

Мы все слишком хорошо знаем, что документация — это, как правило, послесловие, или что-то завершенное после написания тестов и внесения изменений в PR, требующих проверки кода.

Именно поэтому приложение Swimm’s GitHub App анализирует ваши изменения кода, и когда Pull Request становится достаточно интересным для документирования, мы уведомляем вас об этом комментарием и призываем вас создать его. Одним нажатием на кнопку Review Draft in App в нашем комментарии вы переходите в веб-приложение Swimm. Все изменения кода из вашего Pull Request добавляются в документ, и все, что вам остается, — это объяснить, что делает код. Нет никаких правил, как это делать, но в идеале вы хотели бы расположить его в порядке, рассказывающем историю.

Рекомендации по документации

Когда вы изменяете код, по которому есть соответствующая документация, приложение Swimm на GitHub рекомендует вам ознакомиться с документацией. Это помогает пользователям получить доступ к документации по конкретным изменениям кода, предупреждая вас о наличии соответствующей документации в PR.

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

Swimm Verify только для PR-изменений

Мы создали возможность запускать Swimm Verify только для файлов, измененных в Pull Request.

Вот почему: потому что мы знаем, что иногда что-то ломается в основной ветке. Возможно, возник конфликт слияния или два конкурирующих изменения происходят одновременно. И мы знаем, что это может произойти и с вашей документацией. Хотя исправление этих изменений может занять некоторое время, в противном случае они могут не пройти нашу проверку Swimm Verify по всему вашему репозиторию, даже в несвязанных Pull Requests. Поэтому мы считаем целесообразным включить эту функцию до тех пор, пока не будут решены проблемы с вашей основной веткой. Эта функция помогает нашим клиентам избежать ненужных задержек.

Отключение комментариев

Наши инженерные команды работают в быстро меняющейся среде; мы быстро двигаемся, часто ломаем вещи и постоянно работаем над исправлением ошибок.

Поэтому мы разработали приложение Swimm для GitHub с возможностью отключения комментариев. Это позволяет сократить количество уведомлений, которые вы будете получать во время напряженных дедлайнов и критического времени. И, конечно же, у вас всегда есть возможность снова включить комментарии, когда вы захотите.

Интеграция с другими инструментами

Swimm сотрудничает с Atlassian Compass — благодаря этому Swimm входит в экосистему Compass, и вы можете видеть состояние документации по всем вашим распределенным сервисам в одном месте. Вы также можете использовать Интеграцию Compass от Swimm, чтобы связать документацию Swimm с компонентом Compass.

В настоящее время Swimm интегрирует дополнительные инструменты для облегчения понимания общей картины состояния разработки вашего программного обеспечения с учетом документации Swimm.

Doc hooks — скоро появится

Получать рекомендации по соответствующему документу для существующего кода полезно. Но как насчет вновь добавленного кода? Должен существовать способ поиска документации в таких ситуациях, как:

• Когда добавляется новая миграция базы данных → ссылка на вашу политику миграции базы данных
• При изменении конфигурационного файла → ссылка на описание процесса обновления переменных окружения
• При добавлении новой записи в инфраструктуру в виде кода → ссылка на объяснение того, как проверить, что она будет развернута правильно.

Наша команда в Swimm в настоящее время работает над решением именно этих проблем. Мы тестируем альфа-версию функции, которая будет рекомендовать определенный документ при изменении определенного файла или добавлении чего-либо в папку. Следите за новостями!