Czy historia zatwierdzeń powinna być wykorzystywana do przekazywania krytycznych informacji deweloperom?

Podczas spotkania dotyczącego wycofania SDK innej firmy z najnowszej wersji zauważono, że nasi programiści już zaznaczyli w historii zatwierdzeń, że najnowszej wersji nie należy używać.

Niektórzy programiści twierdzili, że była to zła praktyka i powinna była zostać odnotowana w pliku źródłowym (tj. // Don't upgrade SDK Version x.y.z, see ticket 1234) Lub w READMEpliku na poziomie projektu . Inni twierdzili, że skoro historia zatwierdzeń jest częścią dokumentacji projektu, jest to akceptowalna lokalizacja dla takich informacji, ponieważ wszyscy powinniśmy ją czytać.

Czy historia zatwierdzeń powinna być wykorzystywana do przekazywania krytycznych informacji innym programistom, czy powinny być powielane w innej lokalizacji, takiej jak projekt READMElub komentarze w odpowiednim pliku źródłowym?

Gdybym miał zamiar rozważyć aktualizację do nowszej wersji zestawu SDK innej firmy, ostatnie miejsce, które zajrzałbym, to historia systemu kontroli źródła.

Jeśli twój produkt używa wersji SDK 2.0 i ktoś jest zainteresowany aktualizacją do wersji 3.0, nie sądzę, aby rozsądne było sądzić, że powinien on spojrzeć wstecz w czasie w twoim systemie kontroli źródła, aby dowiedzieć się, że to nie jest dobry pomysł.

Tutaj mamy wiki zespołu, które zawiera garść stron z interesującymi informacjami, które czyta każdy programista (konwencje kodowania, jak skonfigurować środowisko programistyczne do budowy produktu, jakie rzeczy osób trzecich należy zainstalować itp.). Jest to miejsce odpowiednie dla ostrzeżenia przed aktualizacją biblioteki strony trzeciej.

Należy to odnotować w historii zmian, ale absolutnie najlepsze miejsce do umieszczenia ogłoszenia jest w tym samym miejscu, w którym zdefiniowano zależność. Jeśli masz na przykład plik maven .pom, który deklaruje twoje zależności od artefaktów, zrobiłbym coś takiego:

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

Bezpośrednio powyżej <dependency>linii.

Problem nr 123 zawierałby szczegółowe informacje o tym, w jaki sposób ulega awarii, zaktualizowana wersja, która spowodowała awarie, i prawdopodobnie powinna zostać ponownie dodana do zaległości w celu późniejszego powrotu - możliwe, że jest jeszcze nowsza wersja, która rozwiązuje problem. Albo automatycznie, edytując bilet, albo ręcznie samodzielnie, wyśle ​​e-mail do zespołu, aby poinformować go o bieżącym problemie, a będąc w module śledzenia, pozwala innym znaleźć go później.

Powodem umieszczenia go w deklaracji zależności jest to, że ktokolwiek chce zmienić wersję, zobaczy ją w momencie, gdy chce ją zmienić i zrozumie, dlaczego nie powinien.

Nie komentowałbym kodu źródłowego, ponieważ mogę łatwo wyobrazić sobie sytuację, w której ktoś sprawdza twoje zależności i zaczyna je aktualizować. Aby to zrobić, nie powinni przeszukiwać bazy kodu dla każdego komentarza do zrobienia.

Odsyłacz do zgłoszenia problemu pozwala ciekawemu programistowi dowiedzieć się, dlaczego się nie udało, i może ponownie go odwiedzić. Bez tego może stać się dość statyczny i nigdy więcej nie będzie aktualizowany.

Krytyczne i nieintuicyjne informacje powinny być udokumentowane tam, gdzie ludzie będą patrzeć rozważając informacje.

W przypadku zespołów i projektów, nad którymi pracowałem, wycofałem się z komentarzem o tym, dlaczego nowa wersja zawiodła. Dodałbym historię zaległości, aby ponownie spróbować uaktualnienia, jeśli nowa wersja zostanie naprawiona. Dodałbym komentarze do systemu kompilacji / skryptów kompilacji, do których biblioteka jest połączona.

Wycofanie zapewni przyszłym programistom kontekst podczas przeglądania historii projektu. Historia zaległości utrzymuje potrzebę tej aktualizacji jako aktywnej części projektu. Komentarze systemu kompilacji mają rację tam, gdzie zmiany będą musiały nastąpić, kiedy biblioteka zostanie ostatecznie zaktualizowana.

Nie komentowałbym tego w kodzie i nie dodawałbym go do README. Deweloperzy planujący wypróbowanie ulepszenia nie będą patrzeć na te elementy. Jeśli go dodasz, to kiedy problem z biblioteką zostanie ostatecznie rozwiązany i uaktualnienie zostanie wykonane, będziesz musiał go usunąć. Ten krok jest często zapominany: powstają notatki, które przynoszą efekt przeciwny do zamierzonego.

Jeśli Twój projekt ma inną konfigurację lub inny przepływ, Twoja odpowiedź może być inna. Myślę, że kluczem jest poprawienie informacji, w przypadku gdy programista zobaczy je podczas prac nad aktualizacją. W ten sposób, jeśli czas na aktualizację nie jest odpowiedni, programista zobaczy ją i zatrzyma, a gdy nadejdzie właściwy czas, zobaczy ją i usunie notatkę, aby nie pomylić przyszłych programistów.

Chciałem zwrócić uwagę Matthew na uwagę, podkreślając jego ważny pomysł w odpowiedzi. Istnieje powód, dla którego nie chcesz aktualizować zestawu SDK, i powód ten powinien zostać zarejestrowany w teście jednostkowym. Nie sprawdzanie numeru wersji, ale faktyczny powód.

Powiedzmy na przykład, że w nowej wersji jest błąd. Napisz test jednostkowy, który sprawdza ten błąd. Jeśli później naprawią ten błąd w zestawie SDK, aktualizacja przebiegnie bezproblemowo. Jeśli wystąpi niezgodna zmiana interfejsu API, napisz test, który sprawdza, czy Twój kod obsługuje nowy interfejs API lub zestaw SDK obsługuje stary interfejs API. To bardziej test integracyjny niż test jednostkowy, ale nadal powinien być wykonalny.

Moja firma generuje 50+ zatwierdzeń dziennie, a my nie jesteśmy do końca ogromni. Nawet jeśli każdy programista czyta każdą wiadomość zatwierdzenia, a szczerze mówiąc, tego nie robi, cały powód, dla którego potrzebujemy zapisanej historii zatwierdzeń, to fakt, że ludzie nie pamiętają. A ludzie nie wracają i nie czytają historii później, chyba że jest problem. I nie mają powodu podejrzewać problemu z aktualizacją, który, o ile wiedzą, jeszcze nie nastąpił.

Oczywiście, wyślij wiadomość e-mail, aby zapobiec powielaniu pracy w najbliższym czasie, i zanotuj ją w skryptach kompilacji oraz w pliku README lub erracie. Jednak szczególnie jeśli problem z nową wersją jest subtelny i czasochłonny w rozwiązywaniu problemów, potrzebujesz sposobu, aby to uczynić oczywistym. To oznacza test jednostkowy.

Przekształcam pytanie jako „Czy powinienem przekazywać krytyczne informacje, które znajdę reszcie zespołu tylko za pośrednictwem wiadomości zatwierdzenia?” Ponieważ myślę, że to oczywiste, że nie, nie powinieneś. Bardzo się staram komunikować (jest to coś, co z mojego doświadczenia wymaga większość zespołów programistycznych) i na pewno robię wszystko, co w mojej mocy, aby uniknąć pułapek lub pozwolić im kłamać.

Gdyby łańcuch działań prowadzących do takiego odkrycia został zainicjowany przez bilet, zaktualizowałbym bilet (i upewniłem się, że ludzie, którzy powinni to wiedzieć, mają widoczność), prawdopodobnie wspomniałbym o tym osobiście (mając nadzieję przynajmniej zostawić komuś coś z dokuczliwym poczuciem, że „Rany, myślę, że Damon powiedział coś o aktualizowaniu tego”), i oczywiście zostawiłbym komentarz w kodzie w momencie, gdy SDK został dołączony, aby nikt nie mógł zaktualizować bez możliwości zobaczenia. Mogę również sprawdzić, czy mógłbym wcisnąć go gdzieś na naszej wiki deweloperów, chociaż robi się to bardziej z myślą o przyszłych pracownikach, a nie o obecnym zespole.

Zajmuje to tylko kilka minut w porównaniu z czasem, który prawdopodobnie upłynął na napotkaniu i odkryciu problemu. Z pewnością nie zdecydowałbym się na jeden z najmniej używanych, słabo sygnałowych fragmentów naszej dokumentacji i zostawię to w tym miejscu.

Powinno być w historii zmian, ale nie tylko w historii zmian, wyobraź sobie na chwilę, że zatrudniasz nowego programistę. Czy oczekujesz, że nowy programista przeczyta każdą wiadomość zatwierdzenia w ciągu ostatnich 10 lat twojego projektu, ponieważ kilka z nich będzie miało kluczowe znaczenie dla zrozumienia twojej bazy kodu?

Po drugie, powiedz, że sytuacja, ale nie zmiany kodu, czy zamierzasz dokonać zatwierdzeń „dokumentacji”, abyś mógł dodawać komunikaty zatwierdzania zgodnie z „komunikat zatwierdzenia z wersji 5432 jest teraz niepoprawny, oto obecna sytuacja”.

Nie jestem pewien, jak Twój zespół komunikuje ale uważam, że najbardziej skuteczny sposób, aby powiedzieć, że to jest pierwszy wysłać e-mail do grupy i email zespołu, oznaczonej jako „pilne” z ciałem mówiąc

Chłopaki, nie możemy używać SDK v xyz, ponieważ powoduje to przepełnienie bufora Foo i awaria usługi Bar. Trzymaj się wersji xyy

Właśnie to zrobiliśmy tutaj i jest to najbardziej niezawodny sposób na przekazanie wiadomości. Jeśli naprawdę chcesz być wybredny (i jeśli Twój system e-mail na to pozwala), poproś o „potwierdzenie odczytu” na e-mailu.

Po poinformowaniu całego zespołu, bardziej szczegółową dokumentację należy umieścić na wiki zespołu. Różni się to w zależności od struktury dokumentacji. Jeśli masz sekcję przeznaczoną specjalnie dla aplikacji Zależności i wymagania, byłoby to dobre miejsce na jej dodanie.

Dodatkowym miejscem do udokumentowania tego rodzaju problemu może być sam kod źródłowy, choć nie zawsze może to działać. Jeśli SDK version ...pojawia się odniesienie tylko w jednym lub dwóch oczywistych miejscach, możesz dołączyć notatkę o nieprzeprowadzaniu aktualizacji.

Historia plików w kontroli źródła może być bardzo długa i, w zależności od programistów, może mieć kilka wpisów dziennie. Ktoś, kto był na wakacjach przez tydzień, może nie mieć czasu na przeczytanie tygodniowej historii popełnień. Plik README jest lepszym miejscem, ponieważ jest nieco bardziej centralny, a ludzie mogą być bardziej skłonni do jego czytania, ale nie możesz zagwarantować, że wszyscy faktycznie przeczytają plik README. Cóż, przypuszczam, że mogą, jeśli zobaczą, że to się zmieniło ...

Coś takiego powinno być umieszczone w komentarzach do zatwierdzenia, ale skorzysta również z bycia w innych miejscach.

Ktokolwiek podejmuje decyzję o aktualizacji, musi znać fakty. Ta osoba może nie żyć w kontroli źródła. Co jeśli ktoś przeczytałby o tym problemie na SO i nigdy nie umieścił go w bazie kodu?

Potrzebny jest jakiś dokument na temat tego zestawu SDK innej firmy.

• Jaki problem rozwiązuje?
• Dlaczego wybrano ten konkretny?
• Jakie kwestie należy wziąć pod uwagę w zakresie: wersji, aktualizacji, testowania itp.
• Kto podejmuje tę decyzję?

Masz przypadek, w którym coś takiego dostało się do kontroli wersji i powinieneś polecić wszystkim, aby korzystali z tych informacji w jak największym stopniu. Tylko twój zespół może zdecydować, gdzie ktoś będzie szukał w dokumentacji, kontroli źródła lub narzędziu do śledzenia błędów, aby uzyskać jak najwięcej informacji na ten temat. W przeciwnym razie zapomnisz, że ktoś i tak to zrobi, i będziesz miał szczęście, jeśli pobudzi to czyjąś pamięć i szybko ją przywróci.

Historia jest doskonałym miejscem do umieszczenia danych przeznaczonych dla czytelnika, który świadomie ich szuka i ma ogólne pojęcie o tym, gdzie powinien być. Jest to bardzo złe miejsce do umieszczania danych, które muszą zostać przekazane użytkownikowi, a nie wyszukiwane.

Historie są bardzo dużymi fragmentami stosunkowo nieposortowanego tekstu. Zazwyczaj mają one na celu dostarczenie programistom szczegółowych informacji o tym, co się zmieniło i dlaczego zostało zmienione. Może to być przeciążenie informacji, chyba że ktoś wie, czego szuka.

Jeśli użytkownik nie wie, czego szuka, informacje są szybko zakrywane pod setkami dzienników zatwierdzeń i nie mają narzędzia do przycinania stosu informacji przed nimi.

Interpretuję tę sytuację jako mającą dwa podstawowe problemy, być może trzy.

• Niepożądane uaktualnienie zestawu SDK dostało się do źródła, gdzie może negatywnie wpłynąć na produkt.
• Z pytania: osoba, która wykonała niechciane uaktualnienie, nie wiedziała o poprzedniej, konkretnej decyzji o odmowie uaktualnienia.

Pierwszy z nich jest moim zdaniem najpoważniejszy. Jeśli niechciane uaktualnienie zestawu SDK może dostać się do kodu, mogą to oznaczać inne problemy.

Ktoś zasugerował dodanie przypadku testu jednostkowego, który zakończy się niepowodzeniem, jeśli wykryje aktualizację. Chociaż zapobiegnie to aktualizacji, uważam, że jest to niebezpieczna ścieżka, która z czasem prowadzi do przepływu lawy . Wydaje się nieuniknione, że w pewnym momencie w przyszłości SDK zostanie zaktualizowany, aby wprowadzić nowe funkcje lub poprawki błędów, lub ponieważ stara wersja nie jest już obsługiwana. Wyobraź sobie porysowanie głowy, a może nawet argumenty, które pojawią się, gdy taki test jednostkowy nie powiedzie się.

Myślę, że najbardziej ogólnym rozwiązaniem jest dostosowanie procesu rozwoju. W przypadku git użyj procesu żądania ściągania . W przypadku Subversion i starszych narzędzi użyj gałęzi i diff. Ale mają pewien proces, który pozwala starszym programistom wychwycić tego rodzaju problemy, zanim wejdą do bazy kodu i wpłyną na innych programistów.

Gdyby w Twojej sytuacji wykorzystano proces żądania ściągnięcia i jeśli każde żądanie ściągnięcia jest wąskie i specyficzne, nie zmarnuje się dużo czasu. Prośba o pobranie aktualizacji SDK zostałaby przesłana i odrzucona z komentarzem, że aktualizacja nie jest pożądana. Nie wpłynęłoby to na nikogo innego i nie byłoby już potrzeby cofania aktualizacji SDK.

Jednak, aby bezpośrednio odpowiedzieć na pierwotne pytanie, zgadzam się z innymi, że oczekiwanie od wszystkich programistów pełnego przeczytania całej historii zmian w kodzie, informacji o wydaniu itp. Dla takich powiadomień jest stratą cennego czasu. Co jest nie tak z krótkim e-mailem zespołu?

Możliwy trzeci problem: dlaczego uaktualnienie nie jest w ogóle potrzebne? Najwyraźniej przynajmniej jeden programista pomyślał, że aktualizacja będzie dobrą rzeczą. Istnieje wiele dobrych powodów, aby opóźniać aktualizację, ale także wiele złych. Uważaj, aby nie dopuścić do przepływu lawy (niepotrzebnego kodu kompatybilności wstecznej) i kultu ładunku („nie możemy tego uaktualnić, ale nie wiem dlaczego”) anty-wzorów!

Powiedziałbym, że dodanie tego rodzaju informacji do historii zatwierdzeń jest w porządku, ale nadal musi być odpowiednio udokumentowane. Niedawno zaczęliśmy używać konfluencji (autor: atlassian). Można go przeszukiwać, możesz ustawić określone strony jako ulubione itp.

Niektóre inne narzędzia mogą być publicznym notatnikiem w dokumentach Evernote lub Google.

Rozwijając odpowiedź Karla, wybrałbym podejście, które automatycznie wymusza ograniczenie w ramach samego procesu meldowania. Potrzebujesz czegoś, co nie wymaga żadnych proaktywnych działań w imieniu programisty, takich jak czytanie doc / wiki / README, i którego nie można ukryć.

W obszarze kontroli źródła TFS można kodować niestandardowe zasady meldowania, które wykonują reguły meldowania. Na przykład można zdefiniować zasadę, która ocenia wersję w pliku konfiguracyjnym z oczekującym zameldowaniem i zakończy się niepowodzeniem, jeśli nie będzie równa xyz. Reguły te faktycznie uniemożliwiają programistom wykonanie zameldowania i mogą dostarczyć komunikat opisowy. Zasady można zastąpić, ale możliwe jest generowanie alertów, gdy to nastąpi.

Alternatywą mogą być bramkowane kontrole, które zakończą się niepowodzeniem, z pewną formą testu jednostkowego, który bezpośrednio lub pośrednio ocenia wersję SDK, jak wspomniał Karl.

Rozumiem, że ta odpowiedź jest bardzo skoncentrowana na TFS, ale możliwe, że podobne funkcje istnieją w systemach kontroli wersji / CI, które mają zastosowanie w twojej sytuacji (jeśli nie TFS).