Kihagyás

Új projekt elkezdése

1. Tag létrehozása az új projekt számára

Mielőtt a projekt repositoryjait létrehoznánk, tageljük le a Semi Product aktuális állapotát.

A tag neve kövesse az alábbi elnevezési konvenciót: 

${projektnev}-init

Ez a tag azért fontos, hogy a későbbiekben könnyebb legyen összehasonlítani milyen fejlesztések kerültek be a Semi productba adott projekt indulásához képest.

Ne felejtsük el, hogy a taget az összes repositoryból meg kell csinálni!

  • api
  • backend
  • frontend
  • documentation
  • bot
  • wizard

Tag létrehozása

A taget létrehozhatjuk egyszerűen a GitLab felületéről az alábbi lépésekkel:

  1. Az aktuális projektbe navigálva a baloldali menüsorból válasszuk ki a Code -> Tags menüpontot.
  2. A megnyíló képernyőn kattintsunk a jobb felső sarokban található New tag gombra.
  3. A New Tag képernyőn:
    1. A Tag name mezőben a fenti névkonvenció szerint adjunk nevet a tagnek.
    2. A Create from mezőben válasszuk ki a develop branchet.
  4. Végül kattintsunk a Create tag gombra.

GitLabCreateTag

2. Git projektek létrehozása

A projektek létrehozásánál induljunk ki a Semi Product kódbázisából. Ennek lépései megtalálhatóak itt.

2.1 Végezzük el a projekt specifikus átnevezéseket

A Semi Product kódbázisában/konfigurációjában vannak Semi Product specifikus elnevezések. Ezeket minden projekten át kell írni a projektnek megfelelő értékekre.

A szükséges átnevezések listája és lépései megtalálhatóak itt.

2.2 Módosítsuk az is-semi kapcsoló értékét

A projekt indulásakor módosítsuk az application.yml-ben a project.is-semi kapcsoló értékét false-ra:

project:
  is-semi: false

2.3 Kapcsoljuk ki a projekten nem szükséges alkalmazásokat, funkciókat, CRON jobokat

A projekt scope-jától függően, lehetnek olyan Semi Product feature-ök, ütemezett feladatok vagy akár komplett alkalmazások, amikre a projekten nincs szükség. Ebben az esetben ne töröljük ki a hozzájuk tartozó kódot, hanem az alábbi lépéseket végrehajtva kapcsoljuk ki őket.

2.3.1 Alkalmazások, funkciók, ütemezetett feladatok és integrációs tesztek kikapcsolása

Az adott funkció és a hozzá tartozó integrácós tesztek az itt leírt módon kapcsolhatók ki.

Alkalmazások kikapcsolása

Előfordulhat, hogy nem egyszerűen egy funkció, hanem egy komplett alkalmazás pl.: admin, partner kikapcsolása szükséges a projekten. Ez az itt leírt módon tehető meg.

2.3.2 Kód lefedettség ellenőrzés kikapcsolása

A kikapcsolt funkcióknál a hozzájuk tartozó tesztek sem fognak lefutni. Emiatt torzul a projekt kódlefedettségi statisztikája.

Ennek elkerülése végett, a kódlefedettség ellenőrzésnél állítsuk be, hogy a kikapcsolt funkciók package-jeit ne ellenőrizze. Ezt az alábbi módon tehetjük meg:

  1. A backend-service mappában található pom.xml-ben keressük meg a jacoco-maven-plugin konfigurációját.

  2. A configuration/excludes listába soroljuk fel a kikapcsolt funkciókhoz tartozó package-eket.

    Kódlefedettség exclude példa

    Ha kikapcsoltuk az admin aktiváció funkciót, akkor az alábbi sort kell hozzáadnunk az excludes listához. 

    <plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <configuration>
        <excludes>
            ...
            <exclude>io/gbsolutions/project/feature/activation/*</exclude>
        </excludes>
    </configuration>
    ...
</plugin>

2.3.3 Szükségtelen release jobok és scriptek kikapcsolása a projekten

2.3.3.1 A generate-aggregated-sql és generate-database-documents jobok kikapcsolása

Alapértelmezetten a release folyamatnak része az Adatbázis dokumentáció, és a „A verzió telepítésekor lefutó SQL scripteket tartalmazó aggregált fájl“ előállítása.

Amennyiben ezekre nincs szükség a projekten, kapcsoljuk ki az ezekhez tartozó release jobokat.

Ehhez egyszerűen a .gitlab-ci-release-flow.yml fájlban tegyünk egy . karaktert az alábbi jobok neve elé:

  • generate-aggregated-sql
  • generate-database-documents

Továbbá vegyük ki a fenti jobokat a ci/.gitlab-ci-create-release-package.yml fájlban található create-release-package job needs szekciójából is.

Végezetül pedig töröljük ki a create-release-package job script szekciójából az alábbi sorokat:

  • - cp -r Database_Documentation_*/* $TAG/Database_Documentation_$TAG/
  • - cp generated/*.sql $TAG/

Az alábbi sort pedig módosítsuk:

- mkdir -p $TAG/Database_Documentation_$TAG

Erre: 

- mkdir -p $TAG

Példa

Kikapcsolt generate-aggregated-sql és generate-database-documents jobok esetén így kell a nevüknek szerepelnie a .gitlab-ci-release-flow.yml fájlban: 

.generate-database-documents:
...
.generate-aggregated-sql:
...

2.3.3.2 A telepítési útmutató másolásának kikapcsolása

A release folyamat része az is, hogy a „Telepítési útmutató“ is belekerüljön a release csomagba.

Amennyiben erre nincs szükség töröljük ki a .gitlab-ci-release-flow.yml fájlban az init-release job script szekciójából az alábbi sort:

  • - !reference [.copy-deployment-guide, script]

2.4 Adatbázis specifikus módosítások elvégzése

DDL-ek definiálása

A Semi Product alapértelmezetten yaml changeSet-ekben definiálja a DDL utasításokat. Erre a Semi Product-on azért van szükség, hogy az induló projektek szükség esetén könnyebben tudjanak Postgres-től különböző adatbázis típussal elindulni. Ez azonban a projekten nem elvárás, nyugodtan definiálhatják SQL fájlokban a DDL-eket a fejlesztők.

2.4.1 Megfelelő dátum típus használata a DDL-ekben

Az src/main/resources/db/changelog mappa almappáiban található scipteket nézzük át, és módosítsuk az összes dátum (timestamptz) mező típusát az adatbázisunknak megfelelő offset információt is tartalmazó dátum típusra.

Minden script, minden timestamptz típusú mezőjét írjuk át datetimeoffset(6)-ra.

Példa a create_auditlog_event_table.yml fájl esetén

databaseChangeLog:
  - changeSet:
      id: 0.0.0:create_auditlog_event_table
      ...
      changes:
        - createTable:
            tableName: auditlog_event
            columns:
              ...
              - column:
                  name: method_start_timestamp
                  type: datetimeoffset(6)

PostgresSQL esetén nincs teendőnk. A timestamptz a PostgreSQL-ben használható offset információt is tartalmazó dátum típus. A Semi Productban minden dátum mező alapértelmezetten ilyen típusú.

Minden script, minden timestamptz típusú mezőjét írjuk át az adatbázisunknak megfelelő offset információt is tartalmazó dátum típusra.

2.4.2 application.yml módosítások

Amennyiben nem PostgreSQL adatbázist használunk a projekten, akkor az application.yml-ben is módosítani kell az adatbázis specifikus paramétereket:

SQL Server adatbázis esetén, az alábbi property-k értékének módosítása szükséges:

  • spring.liquibase.context
  • spring.datasource.url
  • spring.datasource.username
  • spring.datasource.password
  • spring.datasource.driver-class-name
  • spring.quartz.properties.org.quartz.jobStore.driverDelegateClass

Illetve, adjuk hozzá az alábbi property-t:

  • spring.quartz.properties.org.quartz.jobStore.selectWithLockSQL

Példa értékek a fenti propertyk-re SQL Server adatbázis esetén

spring:
  ...
  datasource:
    url: jdbc:sqlserver://localhost:1433;trustServerCertificate=true
    username: sa
    password: Password123
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
  ...
  liquibase:
    ...
    context: filestream, no-ldap
  ...
  quartz:
    ...
    properties:
      org:
        quartz:
          jobStore:
            ...
            driverDelegateClass: org.quartz.impl.jdbcjobstore.MSSQLDelegate
            selectWithLockSQL: SELECT * FROM {0}LOCKS UPDLOCK WHERE LOCK_NAME = ?
            ...

2.4.3 Liquibase context-ek megadása

Ammennyiben nem PostgreSQL adatbázist használunk, az adatbázisunktól függően állítsuk be az alábbi Liquibase context-eket:

Az application.yml fájlban, a spring.liquibase.context property értékéhez, vesszővel elválasztva adjuk hozzá a filestream context-et:

    spring:
      ...
      liquibase:
        ...
        context: no-ldap, filestream
      ...

Az application-dev.yml fájlban, a spring.liquibase.context property értékéhez, vesszővel elválasztva adjuk hozzá a no-filestream context-et:

    spring:
      ...
      liquibase:
        ...
        context: no-ldap, no-filestream
      ...

2.4.4 pom.xml módosítások

Amennyiben nem PostgreSQL-t használunk, úgy backend-service mappában található pom.xml-ben adjuk hozzá az adatbázishoz szükséges dependency-t.

Példa Microsoft SQL Server esetén

    ...
    <dependencies>
        ...
        <dependency>
            <groupId>com.microsoft.sqlserver</groupId>
            <artifactId>mssql-jdbc</artifactId>
        </dependency>
        ...
    <dependencies>
    ...

Illetve az alábbi PostgreSQL specifikus dependency-t töröljük ki: 

        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <scope>runtime</scope>
        </dependency>

Végezetül, ha nem PostgreSQL adatbázisunk van, akkor a liquibase-maven-plugin konfigurációjában is módosítsuk a drivert az adatbázisnak megfelelőre.

Példa Microsoft SQL Server esetén

<configuration>
    <changeLogFile>src/main/resources/db/changelog/db.changelog-master.yaml</changeLogFile>
    <url>${liquibase-plugin.url}</url>
    <driver>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver>
    ...
</configuration>

2.4.5 Logikai típusok értékének módosítása

Adatbázisonként eltérő, hogy milyen értékeket fogad el a boolean típusok értékének.

Ha PostgreSQL adatbázist használunk, akkor nincs teendőnk.

Egyéb esetben módosítanunk kell az src/main/resources/liquibase/versions/0.0.0/script mappában az insert_init_admin.sql fájlban a boolean értékeket az adatbázisnak megfelelőre.

Példa SQL Server adatbázis esetén

SQL Server adatbázis esetén az igaz hamis értékek típusa BIT, így a használható értékek true/false helyett a 0 és az 1.

INSERT INTO auth_user(creation_date_time, username, email, email_verified, application_type, role, active, user_origin,
                      preferred_language)
VALUES (CURRENT_TIMESTAMP, 'admin', 'admin@gbs.demo', 1, 'ADMIN', 'ADMIN', 1, 'INTERNAL', 'HU');
...

2.4.6 .gitlab-ci.yml változók módosítása

Lépés kihagyása

Amennyiben PostgreSQL adatbázist használunk, ez a lépés kihagyható.

Amennyiben nem PostgreSQL-t használunk, úgy a backend projektben található .gitlab-ci.yml fájlunkból töröljük ki az alábbi változókat:

  POSTGRES_USER: $DB_USER
  POSTGRES_PASSWORD: $DB_PASSWORD

Majd adjuk hozzá/frissítsük az adatbázisunk docker image-jéhez szükséges változókat.

Példa mcr.microsoft.com/mssql/server:2017-latest docker image használata esetén

Állítsuk be a DB_USER és DB_PASSWORD változókat: 

  DB_USER: sa
  DB_PASSWORD: Password123
Adjuk hozzá az alábbi mssql image specifikus változókat: 
  SA_PASSWORD: $DB_PASSWORD
  ACCEPT_EULA: "Y"
  MSSQL_COLLATION: Hungarian_CI_AS
Frissítsük az adatbázis docker image specifikus változókat DB_DATASOURCE_URL változókat: 
  DB_IMAGE_NAME: mcr.microsoft.com/mssql/server
  DB_SERVICE_ALIAS: mssql
  DB_IMAGE_VERSION: "2017-latest"
  DB_DATASOURCE_URL: "jdbc:sqlserver://${DB_SERVICE_ALIAS}:1433;trustServerCertificate=true"

2.4.7 Lokális docker-compose.yml fájl módosítása

Amennyiben nem PostgreSQL adatbázist használunk a projekten, úgy a backend projekt infrastucture mappában található docker-compose.yml fájlban is módosítani kell a db service-hez tartozó konfigurációt.

Példa SQL Server adatbázis esetén

SQL Server esetén az itt található konfigurációt tudjuk használni.

2.5 A documentation repository átvétele/bővítése

2.5.1 A repository forkolásának fontossága

A documentation repository átvétele azért fontos, mert a SEMI Product-on történhetnek olyan koncepcionális változások (Pl.: Release folyamat megváltozása), ami miatt az éppen legfrissebb SEMI dokumentáció, már nem érvényes a projektre.

Épp ezért fontos, hogy a projekten elérhető legyen a dokumentáció azon változata, ami az ő kódbázisukra érvényes leírásokat tartalmazza.

2.5.2 A repository bővítése/karbantartása

Miután a projektek lemásolták magukhoz a documentation repository-t, az ő felelősségi körükbe tartozik annak karbantartása, projektspecifikus bővítése.

Amennyiben a csapattagok olyan hiányossággal szembesülnek a projekt során ami a Semi Product szempontjából is fontos lehet, akkor készüljön el a projekten ennek alapján a megfelelő dokumentum, de jelezzük a Semi Product-nak, hogy az új dokumentációt szükség esetén a Semi Product is átvehesse.

Ugyanez igaz arra az esetre, ha a dokumentáció valamely oldala elavultá válna.

Ezen túl az is előfordulhat, hogy a SEMI product javít valamit a dokumentációban, amit a projekten is szükséges átvenni, mert a projekten is releváns ez a leírás. Az ilyen dokumentáció módosításokat/javításokat, a „SEMI alapon futó projektek - Technikai csapat“ chatban a SEMI product bejelenti, az átvételhez szükséges információkkal.

Telepítési útmutatók testreszabása

A legfontosabb lépés a teljes és a verziónkénti telepítési útmutatók frissítése. A projekt indulását követően a lehető leghamarabb frissítsük a telepítési útmutatókat a projektspecifikus paraméterekkel, változókkal, illetve töröljük a projekt számára nem szükséges telepítési lépéseket stb.

2.6 Continous Integration konfigurálása a projekten

A Continous Integration konfigurálásáról itt írunk részletesebben. Fontos, hogy CI a változók kitöltését sem szabad elfelejteni. Lásd itt.

2.7 A csapattag jogosultságok beállítása

Miután a Git projektjeink elkészültek hozzáférést kell adnunk a csapattagoknak a megfelelő jogosultságokkal. A csapattagokat az itt leírt módon lehet a projekthez hozzáadni.

3. JIRA projekt létrehozása

Hozzuk létre és konfiguráljuk be a projekt JIRA-t.

Ennek részletes lépései itt találhatók.

4. GitLab JIRA integráció

4.1 JIRA GitLab integráció

A JIRA GitLab integrációnak automatikusan működnie kell, ha az alábbi feltételek teljesülnek:

  • GitLab-on a projektet a GB Solutions groupon belül hoztuk létre.
  • JIRA-ban a projektet Software project-ként hoztuk létre.

Ennek az integrációnak az eredményeképp a JIRA ticketjeinkben meg kell jelennie a tickethez létrehozott branch-eknek, merge requesteknek, commitoknak, amennyiben ezek nevében szerepel a JIRA ticket azonosítója.

4.2 GitLab JIRA integráció

A GitLab JIRA integrációnak az a szerepe, hogy a GitLab felületén a merge request title-ekben szereplő JIRA ticket azonosítóra kattintva könnyedén át tudjunk navigálni a JIRA az konkrét tickethez.

Fontos, hogy az alábbi konfigurációt projekt subgroup szinten állítsuk be (Pl.: semi-product), és ne specifikus projektenként (Pl.: backend, frontend)

  1. GitLabon lépjünk be a projekt subgroupba, majd a baloldali menüsorból válasszuk ki a Settings -> Integrations menüpontot.
  2. Az Add an integration szekcióból keressük ki és kattintsunk a Jira-ra.

  3. A megnyíló oldalon a Connection details szekcióban állítsuk be az alábbiakat:

    1. Az Enable integration legyen bepipálva.
    2. A Web URL értéke legyen: https://gb-solutions.atlassian.net.
    3. A Jira API URL maradjon üresen.
    4. A Username or email értéke legyen: max.headroom@gbsolutions.io

    5. Az Enter new password or API token értékéhez, kérjük el a Semi csapattól a Jira tokent:

      Név Email cím Telefon Szerepkör
      Katona Áron aron.katona@intuitech.studio +36203160057 Projekt Architekt
      Kazsik Ádám adam.kazsik@intuitech.studio +36702900328 Szenior Fejlesztő
      Surányi Ákos akos.suranyi@intuitech.studio +36203753887 Szenior Fejlesztő

  4. A Trigger szekcióban csak a Merge request legyen bepipálva.

    JiraIntegrationTriggers

  5. Végül kattintsunk a Save changes gombra.

5. Email csoport létrehozása a projekthez

Ajánlott a projekthez külön email csoportot (vagy csoportokat) létrehozni.

Előnyei:

  • Az egész csapatot, vagy a csapat egy részhalmazát érintő leveleknél nem kell egyesével hozzáadnunk a címzetteket.
  • A tesztkörnyezet által kiküldött emailek is érkezhetnek erre a levelezőlistára.

Több levelező lista létrehozása

Természetesen nem csak a teljes csapat számára, hanem kisebb csoportoknak is definiálhatunk levelezőlistákat a projekten.
Pl.: Csak a fejlesztőknek, csak az üzleti csapatnak stb.

  1. A webes Outlookot megnyitva a bal oldali menüben válasszuk ki a Groups menüpontot (3 emberke).
  2. A New email gomb melletti lefelé mutató nyílra kattintva válasszuk ki a New group opciót.
  3. A felugró ablakban töltsük ki a csoport adatait, vegyük fel a tagokat és hozzuk létre a csoportot.
  4. A létrehozást követően megjelenik a felsorolásban az új csoport. A lenti képen látható beállítások (fogaskerék) gombra kattintva megjelenik jobb oldalt egy menü, ahol kattintsunk az Edit group gombra. OutlookEmailGroupSettings
  5. Itt a felugró ablakban az External email settings alatt pipáljuk be a Let people outside the organization email the groups opciót, hogy pl. a Certbot tudjon minket értesíteni a lejáró tanúsítványokról. ExternalEmailSettings

6. Tesztkörnyezet létrehozása

A tesztkörnyezeteink AWS-en futnak, ezért új projekt elkezdése esetén létre kell hoznunk egy új EC2 instance-t a projekthez.

Erre a virtuális gépre lesznek telepítve az alkalmazásaink, és az ehhez szükséges infrastruktúra.

A tesztkörnyezet létrehozása után az erre jogosult csapattagok számára hozzunk is létre felhasználókat a VM-en, hogy tudjanak SSH-val kapcsolódni a VM-hez.

Az EC2 Instance létrehozásának részletes dokumentációja itt található.

7. A Projekt oldal testreszabása

A Projekt oldalon frissítsük be az egyes aloldalakat, hogy a projektre vonatkozó információkat tartalmazzák.