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

Під час зустрічі з приводу відката стороннього SDK від останньої версії було відмічено, що наші розробники вже позначили в історії фіксації, що останню версію не слід використовувати.

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

Чи слід використовувати історію фіксації для передачі важливої ​​інформації іншим розробникам, чи слід дублювати таку інформацію в іншому місці, наприклад, проект READMEабо коментарі у відповідному вихідному файлі?

Якби я збирався переглянути оновлення до нової версії сторонніх SDK, останнє місце, яке я шукаю, - це в історії системи управління джерелами.

Якщо ваш продукт використовує версію 2.0 SDK і хтось зацікавлений у оновленнях до версії 3.0, я не думаю, що доцільно думати, що вони повинні озиратися назад у вашій системі управління джерелом, щоб з’ясувати, що це не дуже гарна ідея.

Тут ми маємо команду вікі, яка містить декілька сторінок із цікавою інформацією, яку читає кожен розробник (кодування умов, як створити середовище розробки для створення продукту, які сторонні речі потрібно встановити тощо). Це місце, яке було б доречним для попередження щодо модернізації бібліотеки третьої сторони.

Це слід зазначити в історії комісій, але найкращим місцем для розміщення повідомлення є те саме місце, де ви визначаєте залежність. Якщо у вас є, наприклад, файл maven .pom, який оголошує ваші артефактні залежності, я б зробив щось на кшталт:

<!-- 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 або errata. Однак, особливо якщо проблема з новою версією є тонкою і забирає багато часу для усунення неполадок, вам потрібен спосіб зробити це очевидним. Це означає одиничне випробування.

Я переробляю питання як "Чи слід повідомляти критичну інформацію, яку я відкриваю іншій команді, лише через повідомлення про прихильність?" Тому що я думаю, що це дає зрозуміти, що ні, ви не повинні. Я дуже намагаюся багато спілкуватись (це, на мій досвід, більшість команд розробників, потрібно докладати активних зусиль), і я, безумовно, роблю все можливе, щоб не створювати підводних каменів або дозволяти їм брехати.

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

Це займає лише ще пару хвилин у порівнянні з часом, який, ймовірно, знадобився для зустрічі та виявлення проблеми. Я, звичайно, не вирішив би один із найменш використаних, малосигнальних фрагментів нашої документації, і залишити це при цьому.

Це має бути в історії комісій, але це має бути не лише в історії комісій, уявіть на мить, як ви наймаєте нового розробника. Чи очікуєте ви, що новий розробник прочитає кожне повідомлення про фіксацію за останні 10 років вашого проекту, тому що пару з них матимуть вирішальне значення для розуміння вашої кодової бази?

По-друге, скажіть, що ситуація не змінюється, але ви збираєтеся робити "документацію", щоб ви могли додавати повідомлення про фіксацію по рядках "повідомлення про фіксацію з редакції 5432 зараз невірне, ось ситуація, що склалася".

Я не впевнений, як спілкується ваша команда, але я вважаю, що найефективніший спосіб сказати це - спочатку надсилати та надсилати електронній пошті групі електронної пошти команди, позначеній як "НЕПРИЄМНА", з тією заявою

Хлопці, ми не можемо використовувати SDK v xyz, оскільки це призводить до переповнення буфера Foo, а служба Bar припиниться. Дотримуйтесь версії xyy

Ось що ми тут зробили, і це найнадійніший спосіб вивести повідомлення там. Якщо ви дійсно хочете бути метушливим (і якщо ваша система електронної пошти дозволяє це), попросіть "прочитати квитанцію" на електронний лист.

Після того, як ви розповісте всій команді, більш детальна документація повинна бути розміщена у командній вікі. Це залежить від того, як ви структуруєте свою документацію. Якщо у вас є розділ, спеціально для ваших програм Залежності та вимоги, це було б хорошим місцем для його додавання.

Додаткове місце для документування подібної проблеми може бути в самому вихідному коді, хоча це може не завжди працювати. Якщо на SDK version ...нього посилається лише одне або два очевидних місця, ви можете включити примітку про не оновлення.

Історія файлів у контролі джерела може бути дуже довгою, і залежно від розробників, може мати кілька записів на день. Хтось, хто тиждень не був у відпустці, може не встигнути прочитати тижневу історію скоєння. Файл README є кращим місцем, оскільки він є трохи більш центральним, і люди можуть бути більш схильні його читати, але ви не можете гарантувати, що всі дійсно прочитають README. Ну, я думаю, вони можуть, якщо вони побачать, що це було змінено ...

Щось подібне повинно було бути включено до коментарів комітету, але це буде корисно від того, щоб бути і в інших місцях.

Той, хто приймає рішення про модернізацію, повинен мати факти. Ця людина може не жити в контролі над джерелами. Що робити, якщо хтось читав би про цю проблему на SO та ніколи не ставив її в кодову базу?

Потрібно мати якийсь документ про цю сторонній пакет SDK.

• Яку проблему вона вирішує?
• Чому саме цього обрали?
• Які міркування потрібно враховувати стосовно: версій, оновлень, тестування тощо.
• Хто приймає це рішення?

У вас є випадок, коли щось подібне пробилося в контроль версій, і вам слід рекомендувати всім використовувати цю інформацію якомога більше. Тільки ваша команда може вирішити, де хто збирається здійснити пошук у будь-якій документації, контролі над джерелами чи у відслідковуванні помилок, щоб отримати якомога більше інформації з цього питання. Інакше ви забудете, хтось все одно це зробить, і вам пощастить, якщо він пробіжить чиюсь пам’ять і швидко поверне її назад.

Історія - чудове місце для розміщення даних, призначених для читача, який свідомо їх шукає, і має загальне розуміння того, де вони повинні бути. Це дуже погане місце для розміщення даних, які необхідно запропонувати користувачеві, а не шукати.

Історії - це дуже великі склади відносно несортованого тексту. Зазвичай вони покликані надати розробнику детальну інформацію про те, що змінилося та чому це було змінено. Це може бути перевантаження інформацією, якщо ніхто не знає, що шукає.

Якщо користувач не знає, що шукає, то інформація швидко закопується під сотні журналів фіксації, і у них немає інструменту, щоб обрізати купу інформації перед ними.

Я трактую цю ситуацію як дві основні проблеми, можливо, три.

• Небажане оновлення SDK перетворило його на джерело, де це може негативно вплинути на продукт.
• З питання: дописувач, який здійснив небажане оновлення, не знав про попереднє, конкретне рішення не оновлювати.

Перший з них, на мою думку, є найсерйознішим. Якщо небажане оновлення SDK може внести його в код, це може призвести до інших проблем.

Хтось запропонував додати тестовий випадок, який не вдасться, якщо виявить оновлення. Хоча це не дозволить здійснити оновлення, я вважаю, що це небезпечний шлях, що призводить до течії лави з часом. Мабуть, неминуче, що в якийсь момент у майбутньому SDK буде оновлено, запровадити нові функції або виправлення, або тому, що стара версія більше не підтримується. Уявіть, що голова чухається, можливо, навіть аргументи, які будуть виникати, коли такий тест одиниці потім не вдасться.

Я думаю, що найзагальнішим рішенням є коригування процесу розвитку. Для git використовуйте процес запиту на тягнення . Для підривних і старих інструментів використовуйте гілки та розл. Але є певний процес, який дозволяє старшим розробникам вловлювати подібні проблеми, перш ніж вони перетворять їх у кодову базу та впливають на інших розробників.

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

Але безпосередньо відповісти на початкове запитання, я погоджуюся з іншими, що сподіваюся, що всі розробники повністю прочитають всю історію редагування коду, випустять нотатки тощо для повідомлень, як це марно витрачає час. Що не так з короткою командою електронної пошти?

Можливе третє питання: Чому оновлення не хочеться в першу чергу? Очевидно, що принаймні один розробник вважав, що оновлення буде хорошою справою. Існує багато вагомих причин затримати оновлення, але також багато поганих. Слідкуйте за тим, щоб уникнути потоку лави (зайвий код сумісності назад) та культу вантажу ("ми не можемо оновити це, але я не знаю, чому") анти-шаблони!

Я б сказав, додавши, що тип інформації для історії чинів є нормальним, але вона все ще повинна бути задокументована належним чином. Нещодавно ми почали використовувати злиття (атласіан). Його можна шукати, ви можете встановити певні сторінки як вибрані тощо.

Деякі інші інструменти можуть бути загальнодоступними блокнотами в документах evernote або google.

Розширюючи відповідь Карла , я б пішов із підходом, який автоматично застосовує обмеження як частину самого процесу перевірки. Вам потрібно щось, що не вимагає жодних ініціативних дій від імені розробника, наприклад, читання doc / wiki / README, і не може бути приховано перекрито.

У землі управління джерелами TFS ви можете кодувати власні політики реєстрації, які виконують правила щодо реєстрації. Наприклад, ви можете визначити політику, яка оцінює версію у конфігураційному файлі з відкладеною реєстраційною карткою, і вона не вийде, якщо вона не дорівнює xyz. Ці правила насправді заважають розробнику виконувати перевірку та можуть надати описове повідомлення. Політику можна відмінити, але можливе сповіщення, коли це станеться.

Альтернативою можуть бути контрольно-провідні контрольні пункти, які не пройдуть, з певною формою одиничної перевірки, яка прямо чи опосередковано оцінює версію SDK, як згадував Карл.

Я вдячний, що ця відповідь дуже орієнтована на TFS, але можливо подібні функції існують у системах управління версіями / CI, які застосовуються у вашій ситуації (якщо не TFS).