Jak pielęgnować źródła klienta?¶

Rozpoczęcie nowego wdrożenia¶

Jeśli rozpoczynamy wdrożenie nowego klienta należy przygotować dla niego repozytorium ze źródłami. Robimy to w następujący sposób:

Tworzymy repozytorium źródeł klienta jako fork z tego repozytorium: git@git.office.sente.pl:dro/s4.git. Nie forkujemy ani submodułu core, ani repozytorium neosa.
Aby pracować na źródłach klienta pobieramy je przez adres zaczynający się od "git@...", a nie od "https", bo tyko wtedy submoduły pobiorą się automatycznie.
Ustawiamy się na branchu wesji, z której chcemy uruchomić klienta, np "5.4" i odbijamy z niego brancha <klient>_master (np. "abakus_master").
Przygotowujemy wszelkie dodatkowe pliki (app, loc, ser) i commitujemy na branchu <klient>_master.
Wpisujemy klienta do zakładki "Stan aktualizacji klientów" w rejestrze aktualizacji wskazując symbol najnowszej aktualizacji z której wystartował klient (np. FKWsparcie8). Dzięki temu będzie jasne od którego momentu zacząć aktualizacje w przyszłości.
Konfigurujemy procesy dystrybucji aplikacji ze źródeł na gicie do stacji końcowych

Zasady tworzenia modyfikacji indywidualnych u klientów¶

Poniższe zasady służą temu, aby do klienta można było w przyszłości łatwo wgrywać aktualizacje.

Wszystkie zmiany dla klienta realizujemy na środowiskach testowych, które mogą być stawiane lokalnie lub budowane na dedykowanych serwerach przez procesy ITS. Nie realizujemy zmian bezpośrednio na środowiskach produkcyjnych. Powody są następujące:

a. każda kompilacja kodu, to ładowanie nowego assembly do pamięci RAM. Stare assembly nie jest wyładowane, może dalej pracować i zabierać RAM. Prędzej czy później doprowadzi to do wykończenia RAMu.

b. każde nowe assembly powstałe w wyniku kompilacji kodu to proszenie się o exceptiony niezgodności typów. I to nie tylko u użytkowników, także w procesach schedulera, handlerów EDA, itp. Więc generuje masę błędów wymagających sprzątnięcia.
Na indywidualne mechanizmy dla klienta należy zrobić osobny projekt neosowy lub nawet kilka.
Na indywidualne zmiany tworzymy osobne struktury X-owe, pola X-owe, triggery X-owe, procedury X-owe, tak aby były łatwo identyfikowalne. Wyjątkiem są zmiany, które są uzgodnione z GP, że są realizowane z celem późniejszego przeniesienia na standard. W przypadku takich zmian w GP uzgadniamy nazewnictwo struktur, po to aby zmiany później przenieść 1:1 na standard.
Unikamy modyfikacji struktur standardowych tak długo, jak się da.

a. Nawet jak nas kusi zmodyfikowanie standardowego triggera, bo chcemy się "wbić" w jakieś miejsce, to lepiej zrobić obok trigger x-owy,

b. potrzebę modyfikacji konsultujemy z odpowiednim kolegium produktowym, czy może od razu zgłosić temat na jakąś poprawkę w standardzie i uzgodnić sposób jej wykonania.
Zmiany oznaczamy komentarzami z XXX + inicjały + komentarz, po co to robimy. Ponadto jeśli zgłaszamy na jirę temat do standardu to do komentarza dodajemy także sygnaturę z jiry. Później przy aktualizacji będzie to podpowiedź, jak rozwiązać potencjalny konflikt w tym pliku.
Staramy się nie modyfikować okien c++. Jeśli potrzebujemy tego dokonać, to albo przenosimy okno do plugina w c++, albo staramy się przenieść to okno do neosa. Jeśli już musimy zmienić kod okna, oznaczamy wszystkie zmiany komentarzami i commitujemy na git. Nie kopiujemy kodu źródłowego do innych folderów, niż są.
Staramy się nie modyfikować standardowych projektów neosowych. Jeśli potrzebujemy je zmodyfikować, to:

a. w pierwszej kolejności staramy się dokonać dziedziczenia z przykryciem w projekcie klienta. Jeśli będzie z tym problem, proszę się zwrócić do Marcina Smereki.

b. Jeśli zmianę już trzeba zrobić, to ją robimy, oznaczamy komentarzami i commitujemy zmienione pliki w orygnalnych folderach. Nie kopiujemy projektów do innych folderów. Jeśli potrzebujemy mieć kilka wersji projektów używamy do tego różnych branchy na gicie a nie różnych folderów.
Zmiany we wstążce, gridach i s_appini robimy na poziomie admina. W przypadku okien neosowych do ustawień grida korzystamy z mechanizmu ustawień widoków.
Zmiany w plikach dbi, raportach robimy w plikach administracyjnych, a nie developerskich.
Na repozytorium klienta commitujemy wszystkie indywidualne zmiany (bazodanowe, c++, dbi, raporty, itp), a to co wchodzi na produkcję powinno znaleźć się na branchu <klient>_master. Można do tego wykorzystać automatyczny proces stworzony przez ITS.

Przygotowanie aplikacji klienta do pierwszej aktualizacji (gdy wykonujemy aktualizację po raz pierwszy u danego klienta)¶

Kiedy stosujemy ten proces? Gdy klient był uruchamiany już daaaawno temu i nikt nie wie, jakie aktualizacje były co klienta wgrane, a jakie nie, albo wiemy, że aplikacja klienta jest bardzo stara i dawno nie była aktualizowana.

Proces składa się z następujących kroków:

Podniesienie bazy klienta do tzw. "wersji zero"
Aplikacja jest co najmniej w wersji zero, gdy ma wgrane wszystkie stare patche i skrypty pomostowe. Stare patche ma wgrane, jeśli w tabeli S_PATCHES jest ostatni wpis z numerem aktualizacji 150804. Jeśli aplikacja nie jest jeszcze w "wersji zero", to należy wykonać poniższe podpunkty:

a. Dla pewności, że zmiany x-owe nie zostaną utracone, warto użyć poniższego zapytania, które pozwoli nam wyciągnąć nazwy struktur, w których mamy zmiany x-owe. Należy wyciągnąć wszystkie zmiany x-owe do skryptów co pozwoli nam na dalszą aktualizację z gwarancją, że nie stracimy zmian klienta.
```
select * from rdb$procedures
where rdb$procedure_name not like 'XK_%'
and rdb$procedure_name not like 'XX_%'
and rdb$procedure_name not like 'X_%'
and rdb$procedure_name not like 'FREE_NUMBER%'
and rdb$procedure_name not like 'MOVE_NUMBER%'
and rdb$procedure_name not like 'SYS_TRANSFER%'
and rdb$procedure_name not like 'SYS_UPDATE_XXX_DESCRIPTION%'
and rdb$procedure_name not like 'EF_X_%'
and (rdb$description is null or upper(rdb$description) not like '%XXX%')-49 procedur po odkomentowaniu
and (lower(rdb$procedure_source) like '%xxx%')
```
b. Należy użyć starego aktualizatora i zainstalować nim patche, które są w folderze x:\apoc\DRO\Patches. Aktualizator znajduje się w x:\apoc\DRO\Patches\!Aktualizator. Konfigurujemy go poprzez uzupełnienie pliku settings.ini (uzupełniamy tam ścieżki oraz user i password /uwaga! password zakodowany/; można password nie uzupełniać, wówczas pojawi się pole do uzupełniania). W przypadku problemów z aktualizatorem, ładujemy jeszcze raz pakiety.

c. Następnie próbujemy wgrać patche (menu jest dość intuicyjne). Ważne, aby s_appini nie miało zdublowanych pozycji; jeśli ma - trzeba je usunąć

d. Po tej operacji baza danych aplikacji klienta powinna być w wersji 4.0.2.

e. Skrypty pomostowe znajdują się w folderze x:\apoc\DRO\Patches\skrypty_pomostowe. Należy do bazy klienta wgrać wszystkie skrypty z przedrostkiem ALL po kolei za pomocą narzędzia Script Executive w IBExpercie. W wyniku ich wgrania baza danych aplikacji klienta powinna być w wersji 4.0.10.

f. Warto porównać te elementy, które zawierały zmiany x-owe, które wyeksportowaliśmy w punkcie a, aby mieć pewność, że nie zniknęły zmiany x-owe, które powinny u klienta zostać.

g. pamietajmy o rekompilacji procedur i triggerów oraz nadanie grantów (SET_ALL_GRANTS_FOR)
Podniesienie źródeł aplikacji klienta (c++, raporty, dbi) do tzw. "wersji zero".
Źródła klienta są co najmniej w wersji zero, gdy są na gicie, a baza danych jest co najmniej w wersji zero i omijaliśmy punkt 1 tej instrukcji. Jeśli któryś z tych warunków nie jest spełniony, to należy wykonać poniższe kroki:

a. Jeśli źródeł klienta nie ma na gicie, lub są, ale repozytorium było utworzone ręcznie, a nie jako fork standardowego repozytorium Teneum, to należy na nowo utworzyć repozytorium źródeł klienta jako fork z tego repozytorium: https://git.office.sente.pl/dro/s4.(przycisk "Fork" w prawym górnym rogu strony). Forkujemy do namespace tego klienta. Nie forkujemy ani submodułu core, ani repozytorium neosa.

b. Ustawiamy się na tagu "wersja_zero" i odbijamy z niego brancha <klient>_master (np. "abakus_master"). Taka postać źródeł jest idealnie zgodna z wersją 4.0.10.

c. Takie źródła porównujemy z tym, co mamy obecnie u klienta (no bo gdzieś mamy źródła, z których aktualnie jesteśmy w stanie skompilować aplikację dla klienta) i nanosimy, to czego brakuje. W szczeólności do nowych źródeł dodajemy kod pluginów (tych w c++) pisanych dla klienta. Ewentualnie nanosimy zmiany indywidualne w standardowych źródłach c++; wykonane dla klienta do tej pory. Jeśli do klienta były wybiórczo przenoszone zmiany ze standardu, to nie musimy ich nanosić.

d. Nanosimy od klienta wszelkie dodatkowe pliki (out\dbi, out\report, out\params) a także pliki konfiguracyjne .app, .loc, *.ser). Wszystko commitujemy na branchu <klient>_master.

e. Upewniamy się, że źródła się kompilują, a aplikacja uruchamia.
Pierwsze przeniesienie bazy na gita.
Skoro mamy już źródła aplikacji na gicie i podniesioną bazę do "wersji zero", należy tą bazę wyeksportować do plików, a pliki zacommitować na gicie. Nawet jeśli ominęliśmy poprzedni punkt, bo już wcześniej mieliśmy źródła na gicie, to najprawdopodobniej, źródła bazy danych są w nieaktualnych formatach plików, więc ten krok najlepiej powtórzyć.

a. Upewniamy się, że w plikach źródłowych klienta jest zarówno folder "dbscripts", jak i folder "standard" z podfolderami (np WORKFLOW, WFFA, itp.) W przynajmniej 7-miu podfolderach folderu "standard" znajdują się kolejne podfoldery "dbscripts" zawierające pliki "shfilter.txt". Jeśli tego nie ma, to coś poszło nie tak w poprzednim punkcie dotyczącym tworzenia źródeł dla klienta. Należy zatrzymać cały proces i wyjaśnić problem.

b. Pobieramy aktualne narzędzie Signature Helper (SH) z kanału stable i konfigurujemy je aby podpiąć je do folderu ze źródłami klienta i lokalnej kopii bazy.

c. Jeśli SH stwierdzi, że pliki są w starym formacie, to pozwalamy mu je przekonwertować. Wyniki konwersji commitujemy.

d. Wykonujemy w SH funkcję "Eksportuj wszystko" z menu "Pełny proces". Czasami ta funkcja może wykazać błędy w widokach i zdublowanych sekcjach s_appini. Jeśli tak się stanie, należy poprawic błędy w bazie danych i ponowić pełny eksport. Wszelkie poprawki powinny się znaleźć w bazie produkcyjnej klienta, aby problem nie powrócił w przyszłości.

e. Należy usunąć zawartość folderu dbscripts\tr - gdyż znajdą się w nim procedury transferowe, które już są w bazie klienta, a więc były tam ręcznie wgrane i ręcznie uruchomione

f. Wynik eksportu należy zacommitować, najlepiej przez polecenie z poziomu git basha: "git add dbscripts/ standard" - bo idzie znacznie szybciej niż spod sourcetree z powodu bardzo dużej ilości plików.
Dla tak przygotowanych źródeł klienta możemy wdrożyć procesy automatycznego commitowania zmian oraz automatycznego deploymentu opisane niżej.

Bieżąca aktualizacja źródeł klienta¶

Proces automatycznego gitowania produkcji na brancha <klient>_master (czyli nasz jenkins_autocommit) - zostanie tu opisany, jak Tomek skończy skrypt.