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

94

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

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

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

rjzii
источник
60
Похоже, у вашего проекта довольно серьезные проблемы со связью.
Церб
82
Вам требуются новые сотрудники, чтобы пройти всю историю коммитов?
Стивен Эверс
3
Новые сотрудники не должны проходить через кодовую базу и менять зависимости без определенного направления для этого.
Midnotion
28
@Midnotion. Итак, где-то на пути от нового найма к основному разработчику вы тратите время на просмотр всей истории коммитов? Захватывающий.
Натан Купер
6
Это все еще не делает хорошей идеей помещать критическую информацию исключительно в историю коммитов.
17 из 26

Ответы:

143

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

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

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

17 из 26
источник
52
Действительно, история коммитов - это история проекта. Точно так же было бы глупо иметь важную информацию в истории правок вики, а не на самой странице. История (будь то код или вики) предназначена для справки о том, что произошло раньше, а не о том, что должно происходить сейчас.
Ордус
48
Если это возможно для вымышленного SDK, я бы добавил модульный тест, разработанный специально для прохождения под V2 и провал под V3 с явным утверждением assert, дающим причину не переходить на V3. История коммитов - это хорошее место, чтобы заявить, почему вы делаете это одно изменение для рецензентов кода, а не для документирования передового опыта.
Klors
3
@Klors До тех пор, пока вы не ограничиваетесь самыми педантичными определениями модульных тестов и отказываетесь от других типов автоматических тестов, тест основан на проверке файловой системы / etc на наличие имени библиотеки (если она имеет закодированную версию в нем) или хэш / контрольную сумму самого файла можно использовать, чтобы бросить красный флаг любому, кто хочет обновить библиотеку, даже в тех случаях, когда недостаток новых версий трудно / невозможно зафиксировать в тесте. (например, многопоточные условия гонки)
Дэн Нили
18
@Klors Я думал о том же, но, на мой взгляд, модульный тест должен продемонстрировать причину использования v2 вместо v3, поэтому , если модульный тест проходит с v4, у вас нет модульного теста, для которого не требуется v2. причина.
Мэтью
9
Еще одна причина не использовать историю фиксации для этого: история фиксации является постоянной записью. Если причина отказа от обновления исчезнет, ​​история коммитов все равно будет содержать предупреждение не обновлять, что может привести к путанице. Вам нужно где-то, где списки требований, подобные этому, обновляются, чтобы разработчикам не приходилось перепроверять, актуальны ли все еще вещи.
Жюль
69

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

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

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

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

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

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

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

Daenyth
источник
11
Я согласен: лучшее место для критической информации - «как можно больше мест». Может быть, pom.xmlили аналогичный файл проекта, readme и т. Д., Но история коммитов все еще хороша. Если я смотрю на обновление библиотеки, я могу проверить историю существующей версии, чтобы увидеть, когда она была обновлена, а также любые заметки о проблемах, которые имел коммиттер. Но я не хотел бы копаться в истории, чтобы собрать всю документацию. Это хороший дополнительный источник.
35

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

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

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

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


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

Джеффри Томас
источник
7
Да, комментарий необходимо поместить «в путь» изменения. Таким образом, технически невозможно выполнить действие, не увидев предупреждение. Это очень похоже на контроль безопасности.
dss539
+1 за предложение создать историю / тикет для обновления в вашем трекере, установите значение «В ожидании» с объяснением того, почему это еще нельзя сделать. Система отслеживания проблем - это то место, куда вы действительно можете требовать, чтобы люди смотрели, прежде чем что-то работать.
Эндрю Спенсер
+1 Цитируя Джеффа Эттвуда (хотя он говорит о «тьфу» о «пользователях»): «В следующий раз, когда вы разрабатываете [X], подумайте о [клиентской] близорукости. Возможно, вы удивитесь, насколько близорукой могут быть ваши [клиенты]. Подумайте долго и усердно о размещении вещей прямо перед ними, где они не просто видны, но неизбежны. Иначе их вообще не будет видно ». blog.codinghorror.com/treating-user-myopia
heltonbiker
17

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

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

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

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

Карл Билефельдт
источник
1
Это единственный верный ответ. Захват сбоя в модульном тесте предотвращает плохое обновление. Период.
Дирк Бестер
15

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

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

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

Damon
источник
4
+1 Настоящее ключевое слово только . Это, конечно, не повредит, если информация хранится в сообщении фиксации в дополнение к другим, более подходящим местам. Он попал в OP, так как журнал фиксации был единственной доступной документацией.
JensG
13

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

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

stonemetal
источник
11

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

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

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

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

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

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

FrustratedWithFormsDesigner
источник
4
Мне нравится идея группы электронной почты. Слишком много мест, где я работал, полагались на отдельные адреса, и вещи не передаются новым членам.
Джеффо
20
Что произойдет, если кто-то новый придет в вашу команду? Кто несет ответственность за предоставление им такого рода псевдоинституциональных знаний?
ABMagil
3
@ABMagil: информация попадает в вики. Разработчики, которые являются новыми для команды, обычно начинаются там, на некоторых вводных страницах. Затем они приходят к конкретным людям (которые предоставили время для помощи новому разработчику), когда у них есть конкретные вопросы (и они всегда так делают). Для нас это, вероятно, в конечном итоге приведено в «Руководстве по установке для разработчиков для ApplicationX», NOTE: Do not use SDK vers. x.y.z because...но первоначальное сообщение должно быть по электронной почте.
FrustratedWithFormsDesigner
16
-1 электронные письма не работают как документация
BlueRaja - Дэнни Пфлугхофт
6
@ BlueRaja-DannyPflughoeft: электронная почта предоставляет простой и простой в использовании метод, позволяющий всем членам команды немедленно узнать, что была обнаружена проблема при использовании определенной версии конкретной библиотеки и что эту версию не следует использовать. Как уже говорилось, долгосрочную документацию лучше всего делать в вики команды или в какой-либо другой базе знаний.
FrustratedWithFormsDesigner
5

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

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

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

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

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

JeffO
источник
2

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

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

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

Корт Аммон
источник
это больше похоже на комментарий, чем на ответ. Смотрите: Как ответить
комнат
Хороший вопрос, я расширил его. Надеюсь, это лучше соответствует критериям StackExchange.
Корт Аммон
Я думаю, что этот ответ лучше всего соответствует теме вопроса. История коммитов хороша для сохранения информации, если человек знает, что он должен искать заметку. Если нет причин проверять «вину» в данной строке, например, включение SDK, эта документация не будет прочитана.
Сет Баттин
1

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

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

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

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

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

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

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

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

wberry
источник
В то время как обновление SDK, которое было второстепенным номером версии, а не основным, было тем, что в конечном итоге привело к этому вопросу, эта группа рассуждений уже давно появляется в группе.
rjzii
Почему запрос на получение ответа был отклонен? Каким образом лицо, ответственное за это решение, должно обнаружить (или запомнить) ограничение версии?
Бен Фойгт
@BenVoigt Ну, либо руководители команд знали об ограничении, либо никто не запомнил его, и это было вновь обнаружено после возникновения проблем. В любом случае, при использовании запросов на извлечение, никто не винит новичка в разработке, так как пожилые люди одобрили бы изменение, прежде чем оно было разрешено.
wberry
@wberry: Или другой старший разработчик обработал запрос извлечения от того, кто знал об ограничении версии. Если не все запросы на получение разрешения должны быть одобрены всеми разработчиками, что выглядит как сомнительная трата ресурсов.
Бен Фойгт
0

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

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

JIMS
источник
0

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

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

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

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

Перо П.
источник