Следует ли использовать историю коммитов для передачи важной информации разработчикам?

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

Некоторые разработчики утверждали, что это плохая практика, и вместо этого ее следует отметить либо в исходном файле (то есть // Don't upgrade SDK Version x.y.z, see ticket 1234), либо в READMEфайле уровня проекта . Другие утверждали, что, поскольку история коммитов является частью проектной документации, она является приемлемым местом для такой информации, так как мы все равно должны ее читать.

Следует ли использовать историю коммитов для передачи критически важной информации другим разработчикам или такую ​​информацию следует дублировать в другом месте, таком как проект READMEили комментарии в соответствующем исходном файле?

Если бы я собирался взглянуть на обновление до более новой версии SDK стороннего производителя, последнее место, на которое я бы обратил внимание, - это история системы контроля версий.

Если ваш продукт использует SDK версии 2.0 и кто-то заинтересован в обновлении до 3.0, я не думаю, что разумно думать, что они должны оглянуться назад во времени в вашей системе контроля версий, чтобы понять, что это не очень хорошая идея.

Здесь у нас есть рабочая вики-группа, содержащая несколько страниц с интересной информацией, которую читает каждый разработчик (соглашения по кодированию, как настроить среду разработки для сборки продукта, какие сторонние компоненты нужно установить и т. Д.). Это именно то место, которое будет подходящим для предупреждения против обновления сторонней библиотеки.

Это должно быть отмечено в истории фиксации, но самое лучшее место для размещения уведомления - это то же место, где вы определяете зависимость. Если у вас есть, например, файл .pom maven, который объявляет ваши зависимости артефактов, я бы сделал что-то вроде:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Прямо над вашей <dependency>линией.

В выпуске № 123 будет подробно рассказано о том, как происходит сбой, версия, которую вы обновили и которая вызвала сбои, и, вероятно, ее следует затем снова добавить в ваш журнал невыполненных работ для повторного рассмотрения - возможно, существует еще более новая версия, которая устраняет проблему. Либо автоматически, отредактировав тикет, либо вручную, он отправит команду по электронной почте, чтобы сообщить им о текущей проблеме сейчас, а находясь в трекере, он позволит людям найти ее позже.

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

Я не стал бы комментировать исходный код, потому что я легко могу представить ситуацию, когда кто-то проверяет ваши зависимости и начинает их обновлять. Для этого им не нужно искать кодовую базу для каждого комментария TODO.

Ссылка на тикет с вопросом позволяет любопытному разработчику узнать, как это не удалось, и, возможно, вернуться к нему позже. Без этого он может стать довольно статичным и никогда не будет обновляться снова.

Важные и неинтуитивные части информации должны быть задокументированы, куда люди будут смотреть при рассмотрении информации.

Для команд и проектов, над которыми я работал, я бы сделал откат с комментарием о том, почему новая версия не удалась. Я бы добавил историю отставания, чтобы повторить попытку обновления, если новая версия исправлена. Я хотел бы добавить комментарии к системе сборки / сценариям сборки, где библиотека связана.

Откат предоставит будущим разработчикам контекст при рассмотрении истории проекта. История отставания сохраняет необходимость этого обновления в качестве активной части проекта. Комментарии системы сборки находятся там, где должны быть изменения, когда библиотека будет наконец обновлена.

Я бы не стал комментировать его в коде и не добавил бы его в README. Разработчики, думающие над попыткой обновления, не будут смотреть на эти части. Если вы добавите его туда, то, когда проблема с библиотекой будет в конечном итоге решена и обновление будет выполнено, вам нужно будет удалить ее. Об этом шаге часто забывают: в результате появляются заметки, которые мешают проекту.

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

Я хотел уделить комментарию Мэтью больше внимания, подчеркнув его важную идею в ответе. Есть причина, по которой вы не хотите обновлять свой SDK, и эта причина должна быть отражена в модульном тесте. Не проверка номера ревизии, а фактическая основная причина.

Например, скажем, есть ошибка в новой версии. Напишите модульный тест, который проверяет эту ошибку. Если они позже исправят эту ошибку в SDK, то обновление будет происходить без проблем. Если есть несовместимое изменение API, напишите тест, который проверяет, поддерживает ли ваш код новый API или SDK поддерживает старый API. Это больше интеграционный тест, чем модульный тест, но все же должен быть выполнимым.

Моя компания генерирует 50+ коммитов в день, и мы не очень большие. Даже если каждый разработчик читает каждое сообщение о коммите, что, честно говоря, они не делают, единственная причина, по которой нам нужна записанная история коммитов, заключается в том, что люди не могут ее запомнить. И люди не возвращаются и не читают историю позже, если не возникнет проблема. И у них нет причин подозревать проблему при обновлении, которая, насколько они знают, еще не произошла.

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

Я переписываю вопрос как «Должен ли я сообщать критически важную информацию, которую я обнаруживаю, остальной части команды только через сообщение коммита? Потому что я думаю, это говорит о том, что нет, не стоит. Я очень стараюсь много общаться (это то, что большинству команд разработчиков, по моему опыту, нужно приложить активные усилия), и я, конечно, делаю все возможное, чтобы избежать создания ловушек или позволить им лгать.

Если бы цепочка действий, приводящих меня к такому открытию, была инициирована тикетом, я бы обновил тикет (и удостоверился, что люди, которые должны знать это, имеют видимость), я бы, вероятно, упомянул его лицом к лицу (надеясь, что по крайней мере, оставить кого-то с некоторым ноющим чувством: «Ну и дела, Деймон сказал что-то об обновлении этого»), и я бы, конечно, оставил комментарий в коде в тот момент, когда SDK был включен, чтобы никто не мог обновить это без возможности увидеть это. Я мог бы посмотреть, смогу ли я сделать это где-нибудь в нашей вики-разработке, хотя это делается скорее с учетом будущего найма, а не текущей команды.

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

Он должен быть в истории коммитов, но не только в истории коммитов. Представьте себе, что вы наняли нового разработчика. Ожидаете ли вы, что новый разработчик будет читать каждое коммит-сообщение за последние 10 лет вашего проекта, потому что пара из них будет иметь решающее значение для понимания вашей кодовой базы?

Во-вторых, скажем, что ситуация, но не изменения кода, собираетесь ли вы делать «документацию» о коммитах, чтобы вы могли добавлять сообщения о коммитах в соответствии с «сообщение о коммите из ревизии 5432 теперь неверно, вот текущая ситуация».

Я не уверен, как ваша команда общается, но я считаю, что самый эффективный способ сказать это - сначала отправить и отправить электронное письмо в группу электронной почты команды, помеченную как «СРОЧНО» с текстом

Ребята, мы не можем использовать SDK v xyz, потому что это приводит к переполнению буфера Foo и аварийному завершению работы сервиса Bar. Палка с версией xyy

Это то, что мы сделали здесь, и это самый надежный способ донести эту мысль. Если вы действительно хотите быть суетливым (и если ваша система электронной почты позволяет это), запросите «квитанцию ​​о прочтении» по электронной почте.

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

Дополнительное место для документирования такого рода проблем может быть в самом исходном коде, хотя это может не всегда работать. Если на SDK version ...него ссылаются только в одном или двух очевидных местах, вы можете включить примечание об отсутствии обновления.

История файлов в системе контроля версий может быть очень длинной и, в зависимости от разработчиков, может иметь несколько записей в день. Кто-то, кто был в отпуске неделю, может не успеть прочитать историю коммитов за неделю. Файл README - лучшее место, так как он немного более центральный, и люди могут быть более склонны его читать, но вы не можете гарантировать, что все действительно прочитают README. Ну, я полагаю, они могут, если увидят, что это изменилось ...

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

Тот, кто принимает решение об обновлении, должен иметь факты. Этот человек не может жить в системе контроля версий. Что если бы кто-то прочитал об этой проблеме в SO и никогда не поместил бы ее в базу кода?

Должен быть какой-то документ об этом стороннем SDK.

• Какую проблему это решает?
• Почему именно этот был выбран?
• Какие соображения необходимо принять во внимание: версии, обновления, тестирование и т. Д.
• Кто принимает это решение?

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

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

Истории - это очень большие тела относительно несортированного текста. Они обычно предназначены для предоставления разработчику подробной информации о том, что изменилось и почему оно было изменено. Это может быть информационная перегрузка, если никто не знает, что они ищут.

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

Я интерпретирую эту ситуацию как наличие двух основных проблем, возможно, трех.

• Нежелательное обновление SDK попало в источник, где это может негативно повлиять на продукт.
• Из вопроса: участник, который выполнил нежелательное обновление, не знал о предыдущем, конкретном решении не обновлять.

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

Кто-то предложил добавить блок модульного тестирования, который не удастся, если он обнаружит обновление. Хотя это предотвратит обновление, я считаю, что это опасный путь, который со временем приводит к потоку лавы . Кажется неизбежным, что в какой-то момент в будущем SDK будет обновлен, чтобы добавить новые функции или исправления, или потому что старая версия больше не поддерживается. Представьте себе головокружительные, может быть, даже аргументы, которые возникнут, когда такой модульный тест провалится.

Я думаю, что наиболее общим решением является корректировка процесса разработки. Для git используйте процесс запроса pull . Для Subversion и более старых инструментов используйте ветки и diff. Но есть некоторый процесс, который позволяет старшим разработчикам улавливать подобные проблемы, прежде чем они попадут в кодовую базу и повлияют на других разработчиков.

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

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

Возможная третья проблема: почему обновление не нужно в первую очередь? Очевидно, что по крайней мере один разработчик думал, что обновление будет хорошей вещью. Есть много веских причин отложить обновление, но есть и много плохих. Старайтесь избегать анти-паттернов потока лавы (ненужный код обратной совместимости) и культа груза («мы не можем это обновить, но я не знаю почему»)!

Я бы сказал, что добавление этого типа информации в историю коммитов - это нормально, но все равно необходимо правильно задокументировать. Недавно мы начали использовать слияние (atlassian). Его можно искать, вы можете установить определенные страницы в избранное и т. Д.

Некоторые другие инструменты могут быть общедоступной записной книжкой в ​​evernote или документах Google.

Продолжая ответ Карла , я бы остановился на подходе, который автоматически применяет ограничение как часть самого процесса регистрации. Вам нужно что-то, что не требует каких-либо активных действий от имени разработчика, например, чтение doc / wiki / README, и которое не может быть скрыто скрыто.

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

Альтернативой могут быть gated-checkins, которые не пройдут, с какой-либо формой модульного тестирования, которая прямо или косвенно оценивает версию SDK, как упоминал Карл.

Я ценю, что этот ответ очень ориентирован на TFS, но, возможно, аналогичные функции существуют в системах контроля версий и CI, которые применяются в вашей ситуации (если не TFS).