В программной инженерии инциденты — это случаи, когда в производственной среде обнаруживаются критические ошибки и проблемы. Они могут быть обнаружены пользователем, автоматизированным тестированием или инженером. Но независимо от этого, инцидентом считается критическая проблема, которая попадает в производственную среду без предварительного обнаружения инженерной командой, тестами или автоматизацией.
Инциденты всегда являются немного деликатной темой — потому ли, что люди не хотят признавать наличие проблем в своем коде, или потому, что они обычно обнажают недостатки и проблемы в наших процессах, которые мы обычно не любим обсуждать.
И это в еще большей степени относится к повторным инцидентам, поскольку их можно было бы избежать, если бы мы просто знали о них. Другими словами, мы бы не поскользнулись на мокром полу, если бы кто-то повесил для нас предупреждающий знак.
Когда речь идет о происшествиях, на ум приходит юридическая концепция «Исключение ошибок и упущений». Как инженеры, мы знаем, что ошибки случаются, и они могут повториться; это довольно часто встречается в индустрии разработки программного обеспечения. Мы понимаем, что люди ошибаются и совершают ошибки, и, конечно, мы должны этого ожидать. И мы также предполагаем, что у них добрые намерения; мы надеемся и ожидаем, что ошибки будут исправлены.
Подумайте об этом: сколько раз вы рефакторизовали код, чтобы избежать ошибки, только для того, чтобы другой инженер совершил подобную ошибку некоторое время спустя? Или сколько раз вы создавали «горячее исправление» для решения определенной проблемы, обещая, что проведете рефакторинг и превратите исправление в постоянное решение?
Вот почему мы должны исправлять эти проблемы, добавлять тесты и процессы, чтобы гарантировать, что они не повторятся, а также документировать произошедшее и делиться знаниями.
Почему разработчики должны документировать инциденты?
Юридическая концепция «Исключены ошибки и упущения» — это, по сути, отказ от ответственности в ситуациях, когда информация быстро меняется. Поэтому бывает трудно получить и тщательно проанализировать ее точный снимок. А код является именно таким — быстро меняющимся, сложным для проверки набором информации, будь то сам код или его окружение.
Один из подходов заключается в написании тестов, чтобы убедиться, что инцидент никогда не повторится. Но хотя тесты важны и полезны, они обычно смотрят на инцидент сквозь призму ошибки в определенной строке кода — это означает, что тест не даст никакой информации о том, как произошел инцидент, что нужно сделать за пределами кода, чтобы избежать подобного инцидента, и какие процессы и изменения необходимы, чтобы предотвратить его повторение.
Вот почему, несмотря на полезность тестов, нам также необходима документация.
Но документация не свободна от потенциальных проблем. Ведь даже если документация по конкретному вопросу создана (а это очень много, если), она обычно устарела, оторвана от кода, ее трудно найти или вообще узнать о ней.
В компании Swimm мы столкнулись с подобными проблемами и создали способ, используя некоторые из наших инструментов Swimm, попытаться решить все эти проблемы. Мы просто добавляем «Знак мокрого пола» в кодовые пути, которые может быть проблематично изменить.
Лучшие практики документирования реагирования на инциденты
Существует множество способов избежать повторения инцидентов, и мы, как разработчики, очень заинтересованы в улучшении наших лучших практик по управлению инцидентами.
Поощряйте документирование
Шаг 1 — это создание документации после обнаружения и устранения определенной проблемы.
Я знаю — поощрять инженеров к созданию документации сложно, но Swimm делает это намного проще благодаря возможности добавления шаблона для отчетов об инцидентах с помощью Swimm’s Templates.
Кроме того, мы также добавили документацию в наше Определение выполненной работы для выпуска горячих исправлений. Например, в версии 0.7.0 у нас возникла проблема, когда наши активы release notes не были добавлены по правильному пути, и мы создали документацию, чтобы кратко описать, что произошло и как мы это исправили.
Прикреплять документацию к коду
В рамках нашего Определения выполненных работ для релизов с горячими исправлениями мы также рекомендуем добавить в документацию фрагмент из кода, который устраняет проблему. В Swimm это не требование, но настоятельная рекомендация.
Как вы можете видеть ниже, мы именно так и поступили, добавив к документу, описывающему горячее исправление, наши заметки о выпуске. Это предупреждение для нас, чтобы мы запомнили наше исправление и не оплошали в следующий раз.
Ведение документации
Добавив фрагмент кода в документ Incident Report, вы сможете отслеживать, если кто-то изменит строки кода, в которых исправлена конкретная проблема. В частности, приложение Swimm для GitHub автоматически пометит документ как автосинхронизированный (при незначительных изменениях) или устаревший, если потребуется повторный выбор фрагмента.
В нашем случае, если кто-то существенно изменил путь кода, связанный с инцидентом, его попросили бы прочитать документацию и отредактировать ее соответствующим образом, привлекая больше внимания к деликатности проблемы. Кроме того, если кто-то рефакторит структуру наших заметок о выпуске, он также должен обновить документацию, содержащую наше предупреждение, и перенести ее в новое место.
А при более незначительных изменениях Swimm может автоматически синхронизировать ваш документ и зафиксировать его непосредственно в вашем Pull Request.
Легко находите документацию, когда она вам нужна
Запрашивая фрагмент для добавления в документ Incident Report, Swimm делает его доступным для обнаружения с помощью нашего плагина IDE во время написания кода. Поэтому каждый, кто добавляет заметку о новом выпуске, видит документацию по горячим исправлениям, помеченную на этот объект.
Более того, поскольку Swimm хранит вашу документацию в виде markdown-файлов вместе с вашим кодом, вы можете осуществлять глобальный поиск по таким фразам, как «hotfix» или «incident», и вы сможете найти и прочитать соответствующую документацию, не выходя из IDE. Таким образом, каждый раз, когда кто-то добавляет новый элемент в наш массив releaseNotes, он увидит, что существует соответствующий документ с «Hotfix» в названии.
У нас также есть список воспроизведения отчетов об инцидентах, в котором собраны все наши отчеты, и который может помочь другим людям при внедрении и столкновении со знакомой проблемой. Это важный способ для менеджеров следить за чтением и пониманием инцидентов и исправлений в своих командах.
Кроме того, отправляя в Slack электронные письма с уведомлением о новых документах, вы можете привлечь больше людей к просмотру новой документации, которая была добавлена.
Итог
Хотя некоторые инциденты неизбежны, с Swimm у вас будет меньше шансов повторения подобных инцидентов в будущем и больше шансов устранить проблемы или скорректировать области, которые долгое время не решались.
Платформа Swimm использует множество инструментов, таких как наше веб-приложение, приложение GitHub и расширения IDE, которые облегчают работу над документацией, связанной с кодом, ее ведение и поиск, когда она вам больше всего нужна.
Если вы хотите получить уверенность в том, что ваш знак мокрого пола будет обработан с помощью платформы Swimm, узнайте больше о Swimm и присоединяйтесь к нашей открытой бета-версии уже сегодня. Скольжения и падения, которых можно избежать, экономят бесчисленные часы времени и нервотрепки. И вы сможете раздавать свои знаки мокрого пола.