Release

1. Előkészületek - Fontos teendők minden release előtt

1. A releaselendő verzióhoz tartozó SQL scripteket olvassuk át, hogy jónak tűnnek-e.
   Gondoljuk át, hogy biztosan minden környezeten le tudnak-e futni majd a scriptek, nem maradt-e ki migrációs script stb.

2. Nézzük meg, hogy a releaselendő verzióhoz lett-e létrehozva megfelelő Deployment Guide (Telepítési útmutató).
   Amennyiben hiányzik, ezen a ponton kell megírni és commitolni a repositoryba.

   • A Telepítési útmutatóba azt is írjuk bele, hogy konkrétan melyik docker image verziókat telepítjük, mely konfigokat kell frissíteni, hol kell átírni a verziószámokat stb.
   • Továbbá figyeljünk arra, hogy a lépések logikusan legyenek sorrendbe rendezve. Az összetartozó elemek (pl. HAProxy konfiguráció, Alkalmazás konfiguráció) egy helyre legyenek csoportosítva stb.

3. A docker imagek buildelését követően telepítsük a friss verziót AWS-re.

   • AWS-en végezzünk smoke tesztelést.

4. A tesztelést követő lépés a docker imagek eljuttatása az ügyfél környezetre. Leírás itt.

A documentation project releaselése

Feltűnhet, hogy a documentation repository nem szerepel az alábbi parancsokban. Ez szándékos, a documentation repository-t nem kell az alkalmazással együtt releaselni, és az OBR folyamatnak sem része.

2. Releasek fajtái

Két kategóriát különböztetünk meg:

1. Ütemezett normál release
   • Értelemszerűen ebbe a kategóriába tartozik minden tervezett release. Az ütemezett release-ek scope-ja és a kiadás dátuma előzetes tervezés alapján kerül meghatározásra.
2. Hotfix release
   • Sprint közben, normál release-ek között lehet szükséges a kiadása. A Hotfix release-ek akkor szükségesek, ha olyan hibát tapasztalunk a production környezeten, aminek javítása nem várhat a következő ütemezett release kiadásáig.

3. Release Verziózás

Az alkalmazások verziózásához a MAJOR.MINOR.PATCH formátumát használjuk, az alábbi szabályok szerint:

1. A MAJOR verziószámot abban az esetben növeljük ha tervezett releaset adunk ki.
   Pl.: Az 1.0.0 verzió után kiadjuk a 2.0.0 verziót.
2. A MINOR verziószámot akkor növeljük, ha adott verzión belül új feature vagy Change Request kiadása szükséges.
   Pl.: A 2.0.0 verzió egyik funkciójához kérnek egy módosítást, amit a 2.1.0 verzióban adunk ki.
3. A PATCH verziószámot a nem tervezett hotfix releasek esetén növeljük.
   Pl.: Az 2.1.0 verzióban találnak egy hibát amit a következő tervezett release előtt ki kell adni a 2.1.1 verzióban.

Verziózás a gyakorlatban

• Normál tervezett release esetén:

  • Ha a fejlesztési verzió: 1.0.0-SNAPSHOT
  • Akkor a releaselt verzió: 1.0.0
  • A következő fejlesztési verzió: 2.0.0-SNAPSHOT

• Normál tervezett de csak 1 funkció módosítását tartalmazó release esetén:

  • Ha a fejlesztési verzió: 1.1.0-SNAPSHOT
  • Akkor a releaselt verzió: 1.1.0
  • A következő fejlesztési verzió: 2.0.0-SNAPSHOT

• Nem tervezett hotfix release esetén:

  • Ha a fejlesztési verzió: 1.1.1-SNAPSHOT
  • Akkor a releaselt verzió: 1.1.1
  • A következő fejlesztési verzió: 2.0.0-SNAPSHOT

4. Gitflow

A megfelelő release és hotfix branchek létrehozásakor, illetve mergelése során a Gitflow-t követjük.

A projekten használt branchelési módszerekről, a branchek fajtáiról és szerepéről itt található részletesebb információ.

5. Absztrakt release folyamat leírása

5.1 Ütemezett normál release esetén

1. A develop branchből készítünk egy release branchet.
2. A release branchen véglegesítjük a kódot. Pl.: Teszteljük és ha esik ki bug, akkor ezen a branchen javítjuk.
3. Befrissítjük az API verziót, amennyiben szükséges.
4. A release branchen elkészítjük a release-t.
5. A tag-ekből docker imageket buildelünk és a container registrybe pusholjuk megfelelő verziózással ellátva. Lásd itt.
6. A fentiek után mergeljük a release branchet a main branchre.
7. Ezt követően mergeljük a develop branchre is feloldva az esetleges conflictokat.

5.2 Hotfix release esetén

1. A main branchből készítünk egy hotfix branchet.
2. Befrissítjük az API verziót, amennyiben szükséges.
3. A hotfix branchen elkészítjük a release-t.
4. A tag-ből docker imageket buildelünk és a container registrybe pusholjuk megfelelő verziózással ellátva. Lásd itt.
5. A fentiek után mergeljük a hotfix branchet a main branchre.
6. Ezt követően mergeljük a develop branchre is feloldva az esetleges conflictokat.

6. Release folyamat a gyakorlatban

git merge a védett branchekre

A develop branchre történő mergelés során lehetnek feloldásra váró conflict-ok. Különösen olyankor, amikor sokáig zajlik a fejlesztés párhuzamosan a release/hotfix illetve develop brancheken. Ilyen esetekben indokolt úgynevezett köztes branchen feloldani a conflictokat. Ez a gyakorlatban azt jelenti, hogy amikor a release során az alábbi parancsokhoz érünk:

$ git checkout develop
$ git merge release/x.y.z
$ git push

Akkor a develop branch helyett a köztes branchünket kell checkoutulnunk és arra mergelni a release/x.y.z branchet:

$ git checkout merge-x.y.z-into-develop
$ git merge release/x.y.z
$ git push

Amennyiben a merge sikeres (CI nem törik el a köztes branchen, az alkalmazás elindul stb.), a köztes branch már egyszerűen (conflictok nélkül) mergelhető a develop-ba.

$ git checkout develop
$ git merge merge-x.y.z-into-develop
$ git push

A köztes branchek használatáról, elnevezési konvenciójáról stb. itt olvashatsz részletesebben.

push a védett branchekre

Tartsuk észben, hogy a release végeztével mergelni kell a release/hotfix brancheket a védett branchekre (main és develop) majd ezt pusholni is kell a remotera.

Ezt azonban csak a megfelelő jogosultsággal rendelkező felhasználók tudják megtenni. Amennyiben semelyik felhasználónak nincs ehhez jogosultsága, akkor a release idejére a repository beállításainál módosítani kell a push jogosoltságokat a védett branchekre.

Az x.y.z helyére a megfelelő verziószámot kell írni.

6.1 Ütemezett normál release

Jelenleg a normál release során minden projektet releaselünk, hogy szinkronban tartsuk az egyes projektek verziószámait. Ezáltal pedig az ügyfelek számára is követhetőbb lesz milyen verziót kapnak és telepítenek.

Ez a gyakorlatban azt jelenti, hogy abban az esetben is releaselni kell például az api és frontend projekteket, ha csak a backend-ben volt tényleges módosítás stb.

6.1.1 api release

Az api szeparált releaselése

Előfordulhat, hogy a projekten korábban elkészül a kontrakt az alkalmazások között és pl.: a mobil számára már előre kiadtuk a megfelelő api verziót.

Ilyenkor értelemszerűen nem szükséges ezen a ponton releaselni az api-t, amennyiben azóta nem történt benne a frontend és backend projekteket érintő módosítás.

Továbbá, ilyenkor a backend és frontend projektek release-e során, a pom.xml-ben és package.json-ben is a korábban releaselt api verziószámát kell megadni.

Az api projekt releaseléséhez az alábbi parancsokat kell parancssorból kiadni:

6.1.1.1 Release branch nyitása

$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout develop # Álljunk rá a develop branchre.
$ git pull # Álljunk rá a friss developra.
$ git checkout -b release/x.y.z
$ git push --set-upstream origin release/x.y.z

6.1.1.2 Release kiadása

$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout release/x.y.z # Álljunk rá a release branchre.
$ git pull # Álljunk rá a friss release branchre

A common/meta mappában található meta-data.yml fájlban frissítsük a ‘version:’ értékét az x.y.z verziószámra:

openapi: 3.0.0
info:
  ...
  version: x.y.z
  ...

$ git commit --allow-empty -a -m "[release] prepare release x.y.z"
$ git push
$ git tag x.y.z
$ git push origin x.y.z
$ git checkout main
$ git merge release/x.y.z
$ git push
$ git checkout develop
$ git merge release/x.y.z
$ git push
$ git checkout release/x.y.z
$ cd generate
$ npm run generate:api
$ cd ..
$ curl --user "$DOCKER_REGISTRY_USERNAME:$DOCKER_REGISTRY_PASSWORD" --upload-file openapi-backend.yml "https://gitlab.com/api/v4/projects/$BACKEND_PROJECT_ID/packages/generic/api/x.y.z/openapi-backend.yml"
$ curl --user "$DOCKER_REGISTRY_USERNAME:$DOCKER_REGISTRY_PASSWORD" --upload-file openapi-web.yml "https://gitlab.com/api/v4/projects/$BACKEND_PROJECT_ID/packages/generic/api/x.y.z/openapi-web.yml"
$ curl --user "$DOCKER_REGISTRY_USERNAME:$DOCKER_REGISTRY_PASSWORD" --upload-file openapi-mbl.yml "https://gitlab.com/api/v4/projects/$BACKEND_PROJECT_ID/packages/generic/api/x.y.z/openapi-mbl.yml"

A fenti curl parancsokban:

• A $DOCKER_REGISTRY_USERNAME placeholder helyére a GitLab deploy token username-et kell behelyettesíteni.
• A $DOCKER_REGISTRY_PASSWORD placeholder helyére a GitLab deploy token password-ot kell behelyettesíteni.
• A $BACKEND_PROJECT_ID placeholder helyére a backend projekt GitLab-os project id-ját kell behelyettesíteni.
• Az x.y.z placeholder helyére a verziószámot kell behelyettesíteni.

6.1.2 backend release

Az backend projekt releaseléséhez az alábbi parancsokat kell parancssorból kiadni:

6.1.2.1 Release branch nyitása

$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout develop # Álljunk rá a develop branchre.
$ git pull # Álljunk rá a friss developra.
$ git checkout -b release/x.y.z
$ git push --set-upstream origin release/x.y.z

6.1.2.2 Release kiadása

$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout release/x.y.z # Álljunk rá a release branchre.
$ git pull # Álljunk rá a friss release branchre

Frissítsük az API verziót a backend-service mappában található pom.xml-ben:

    <properties>
        ...
        <project-api.version>x.y.z</project-api.version>
    </properties>

$ git commit --allow-empty -a -m "[release] prepare release x.y.z"
$ git push
$ git tag x.y.z
$ git push origin x.y.z

$ git checkout main
$ git merge release/x.y.z
$ git push
$ git checkout develop
$ git merge release/x.y.z
$ git push

6.1.3 frontend release

Az frontend projekt releaseléséhez az alábbi parancsokat kell parancssorból kiadni:

6.1.3.1 Release branch nyitása

$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout develop # Álljunk rá a develop branchre.
$ git pull # Álljunk rá a friss developra.
$ git checkout -b release/x.y.z
$ git push --set-upstream origin release/x.y.z

6.1.3.2 Release kiadása

$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout release/x.y.z # Álljunk rá a release branchre.
$ git pull # Álljunk rá a friss release branchre

Frissítsük az API verziót a package.json fájlban:

 {
  ...
   "config": {
    ...
    "project_api_version": "x.y.z",
    ...
  },
  ...
}

$ git commit --allow-empty -a -m "[release] prepare release x.y.z"
$ git push
$ git tag x.y.z
$ git push origin x.y.z
$ git status # Ellenőrizzük hogy nem maradt változtatás a branchen.

$ git checkout main
$ git merge release/x.y.z
$ git push
$ git checkout develop
$ git merge release/x.y.z
$ git push

Utolsó lépésként pusholjuk a docker image-eket!

6.2 Hotfix release

Jelenleg a hotfix release során minden projektet releaselünk, hogy szinkronban tartsuk az egyes projektek verziószámait. Ezáltal pedig az ügyfelek számára is követhetőbb lesz milyen verziót kapnak és telepítenek.

Ez a gyakorlatban azt jelenti, hogy abban az esetben is releaselni kell például az api és frontend projekteket, ha csak a backend-ben volt tényleges módosítás stb.

A hotfix release során, a main branchből csinálunk hotfix branchet, majd ez megy vissza a develop-ra és main-re is. A hotfix branchre történő fejlesztéseket követően.

6.2.1 api hotfix

Az api szeparált releaselése

Előfordulhat, hogy a projekten korábban elkészül a kontrakt az alkalmazások között és pl.: a mobil számára már előre kiadtuk a megfelelő api verziót.

Ilyenkor értelemszerűen nem szükséges ezen a ponton releaselni az api-t, amennyiben azóta nem történt benne a frontend és backend projekteket érintő módosítás.

Továbbá, ilyenkor a backend és frontend projektek release-e során, a pom.xml-ben és package.json-ben is a korábban releaselt api verziószámát kell megadni.

Az api projekt releaseléséhez az alábbi parancsokat kell parancssorból kiadni:

6.2.1.1 Hotfix branch nyitása

$ git checkout main
$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout -b hotfix/x.y.z
$ git push --set-upstream origin hotfix/x.y.z

Ezt kövessék a hotfix branchen a kiadni kívánt javítások.

6.2.1.2 Hotfix kiadása

$ git checkout hotfix/x.y.z
$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git pull # Álljunk rá a friss hotfix branchre.

A common/meta mappában található meta-data.yml fájlban frissítsük a ‘version:’ értékét az x.y.z verziószámra:

openapi: 3.0.0
info:
  ...
  version: x.y.z
  ...

$ git commit --allow-empty -a -m "[release] prepare release x.y.z"
$ git push
$ git tag x.y.z
$ git push origin x.y.z
$ git checkout main
$ git merge hotfix/x.y.z
$ git push
$ git checkout develop
$ git merge hotfix/x.y.z
$ git push
$ cd generate
$ npm run generate:api
$ cd ..
$ curl --user "$DOCKER_REGISTRY_USERNAME:$DOCKER_REGISTRY_PASSWORD" --upload-file openapi-backend.yml "https://gitlab.com/api/v4/projects/$BACKEND_PROJECT_ID/packages/generic/api/x.y.z/openapi-backend.yml"
$ curl --user "$DOCKER_REGISTRY_USERNAME:$DOCKER_REGISTRY_PASSWORD" --upload-file openapi-web.yml "https://gitlab.com/api/v4/projects/$BACKEND_PROJECT_ID/packages/generic/api/x.y.z/openapi-web.yml"
$ curl --user "$DOCKER_REGISTRY_USERNAME:$DOCKER_REGISTRY_PASSWORD" --upload-file openapi-mbl.yml "https://gitlab.com/api/v4/projects/$BACKEND_PROJECT_ID/packages/generic/api/x.y.z/openapi-mbl.yml"

A fenti curl parancsokban:

• A $DOCKER_REGISTRY_USERNAME placeholder helyére a GitLab deploy token username-et kell behelyettesíteni.
• A $DOCKER_REGISTRY_PASSWORD placeholder helyére a GitLab deploy token password-ot kell behelyettesíteni.
• A $BACKEND_PROJECT_ID placeholder helyére a backend projekt GitLab-os project id-ját kell behelyettesíteni.
• Az x.y.z placeholder helyére a verziószámot kell behelyettesíteni.

6.2.2 backend hotfix

Az backend projekt releaseléséhez az alábbi parancsokat kell parancssorból kiadni:

6.2.2.1 Hotfix branch nyitása

$ git checkout main
$ git checkout -b hotfix/x.y.z
$ git push --set-upstream origin hotfix/x.y.z

Ezt kövessék a hotfix branchen a kiadni kívánt javítások.

6.2.2.2 Hotfix kiadása

$ git checkout hotfix/x.y.z
$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git pull # Álljunk rá a friss hotfix branchre.

Frissítsük az API verziót a backend-service mappában található pom.xml-ben:

    <properties>
        ...
        <project-api.version>x.y.z</project-api.version>
    </properties>

$ git commit --allow-empty -a -m "[release] prepare release x.y.z"
$ git push
$ git tag x.y.z
$ git push origin x.y.z
$ git checkout main
$ git merge hotfix/x.y.z
$ git push
$ git checkout develop
$ git merge hotfix/x.y.z
$ git push

6.2.3 frontend hotfix

Az frontend projekt releaseléséhez az alábbi parancsokat kell parancssorból kiadni:

6.2.3.1 Hotfix branch nyitása

Miután új hotfix branchet nyitunk a main-ről, frissítsük az alkalmazás verzióját a hotfix verzióra:

$ git checkout main
$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git checkout -b hotfix/x.y.z
$ git push --set-upstream origin hotfix/x.y.z

Ezt kövessék a hotfix branchen a kiadni kívánt javítások.

6.2.3.2 Hotfix kiadása

$ git checkout hotfix/x.y.z
$ git status  # Ellenőrizzük hogy nincs változtatás azon a branchen ahol állunk.
$ git pull # Álljunk rá a friss hotfix branchre.

Frissítsük az API verziót a package.json fájlban:

 {
  ...
   "config": {
    ...
    "project_api_version": "x.y.z",
    ...
  },
  ...
}

$ git commit --allow-empty -a -m "[release] prepare release x.y.z"
$ git push
$ git tag x.y.z
$ git push origin x.y.z
$ git status # Ellenőrizzük hogy nem maradt változtatás a branchen.

$ git checkout main
$ git merge hotfix/x.y.z
$ git push
$ git checkout develop
$ git merge hotfix/x.y.z
$ git push

Utolsó lépésként pusholjuk a docker image-eket!

6.3 Docker imagek pusholása

Az alábbi lépéseket a backend és frontend projektek esetén is végig kell csinálni.

1. GitLab-on nyissuk meg a projekt repository-ját.
2. A baloldali menüsorból kattintsunk a CI/CD -> Pipelines menüpontra.
3. Kattintsunk a Run pipeline gombra.
4. A Run for branch name or tag mezőben válasszuk ki a tag-et, amit releaseltünk.
5. Kattintsunk Run pipeline gombra.

6. Indítsuk el az összes release jobot ami definiálva van az adott projekthez:

   • Backend: release-docker-images-backend
   • Frontend: release-docker-images-frontend-admin, release-docker-images-frontend-client, release-docker-images-frontend-partner