CDB Komponenten¶

CDB Komponenten

Komponenten Architektur & verteilte Entwicklung

mit CIM DATABASE / CONTACT Elements

Themen

• CDB Pakete

• Struktur Kundenpaket

• Voraussetzungen + repair Schema & Konfiguration

• Updates & Konflikte + cdbpkg & SCM big picture

• Transport: Code & Config Merge-Schaubild

• CDB & SCM-System

• Merge Strategien

• Lieferantenanbindung: Beauftragung & Auslieferung

• Entwicklungszweige mergen

CDB Pakete

Hersteller-Pakete in site-packages

Änderungen nur durch Hersteller-Updates

Beispiel: keine eignen Änderungen an cs. Paketen

Kunden-Paket cust.plm darf nicht im Python-Pfad (site-packages) liegen.

Namensräume, Pakete & Ebenen

• Ebene 3 – cust. pflegt der Customer

• Ebene 2 – tpm. pflegt der Third Party Maker

• Ebene 1 – cs. pflegt die Contact Software GmbH

Dependency-Direction: 3 darf 2 oder auch 1 anpassen

cust. –> tpm –> cs.

Anpassungen des Customer

1. Quellcode in cust.

   Anpassung z.B. durch Verbung aus cs. und tpm. oder Signalhandler die in cs. und tpm. registriert werden.

2. Konfiguration aus cs. und tpm. die der Customer ändern muss

   z.B. Anpassungen an Masken & Tabellen aus cs. und tpm.

app_conf

Master + Historie für jedes CDB-Modul, wird aus der DB aufgebaut, von cdbpkg verwaltet und wird nicht im SCM-System versioniert!

CADDOK_BASE
  +---app_conf
      +---cs
      |   ...
      |   \---erp
      |       +---current
      |       +---history
      |       \---master
      + ...
      \---cust.plm

Struktur cust.plm Paket (1)

CDB-Paket mit zwei CDB-Modulen cust.plm und cust.foo

\---cust.plm             # CDB-Paket
    +---cust.plm.egg-info
    |   setup.py         # schauen wir uns gleich an
    |                    #   ansonsten keine weiteren Dateien
    \---cust             # Python Namespace 'from cust import foo'
        | __init__.py    #   ist ein Python (kein CDB) Paket
        |                #   ansonsten keine weiteren Dateien
        +---plm          # Modul 'plm' nicht zwingend erforderlich
        \---foo          # Modul 'foo' schauen wir uns gleich an

Struktur cust.plm Paket (2)

\---cust.plm             # CDB-Paket
    +---cust.plm.egg-info
    |   setup.py         # schauen wir uns gleich an
    |                    #   ansonsten keine weiteren Dateien
    \---cust             # Python Namespace 'from cust import foo'
        | __init__.py    #   ist ein Python (kein CDB) Paket
        |                #   ansonsten keine weiteren Dateien
        +---plm          # Modul 'plm' nicht zwingend erforderlich
        \---foo          # Modul 'foo' schauen wir uns gleich an

cust.plm setup.py

from cdb.comparch.pkgtools import setup
setup(
    name               = "cust.plm" # package name
    , version          = "1.0.0"    # package version
    # list of required packages
    , install_requires = [
        'cs.platform', 'cs.base', 'cs.workflow' ..]
    # relative path for each documentation
    , docsets          = []
    # list of contained modules (cdb_modules.txt)
    , cdb_modules      = ['cust.plm', 'cust.foo', ..]
    # list of services (class names cdb_services.txt)
    cdb_services       = []
  ],

Modul cust.foo

\--foo                      # CDB 10.x
   |  module_metadata.json
   |  content_metadata.json # in 15.x unter ./configuration
   |  schema.json           # in 15.x unter ./configuration
   +---patches              # in 15.x unter ./configuration
   +---configuration
   \---resources

\--foo                      # CDB 15.x
   |  module_metadata.json
   +---configuration
   \---resources

configuration Ordner vom CDB-Modul cust.foo

\--configuration
   |  content_metadata.json          # Checksumme
   |  schema.json                    # DB Schema
   +---content                       #
   |   |   ausgaben.json             # eigene Meldungstexte
   |   |   browsers.json             # eigene Auswahlbrowser
   |   \---blobs                     # eigene BLOBs
   |           6eccde35-1fa8-...     # --> z.B. Report-Template
   \---patches                       # Anpassungen andere Module
       +---cs.pcs.projects           # --> cs.pcs.projects
       |   |   patches.json          #     patch Konfiguration
       |   \---blobs                 #     patch blobs
       |           12eeddaa-17fa-... #
       +---cs.pcs.cheklists          # --> cs.pcs.checklists
       |       patches.json          #     patch Konfiguration

Voraussetzungen

Instanz & DB müssen immer zueinander passen.

DB Schema muss im Data-Dictionary vollständig den Modulen zugeordnet sein.

Referenzielle Integrität der Konfiguration muss gewährleistet sein.

Konflikte müssen aufgelöst werden!

schema -- check & repair

$ cdbpkg schema_coverage

• tmp/cdbpkg_schema_coverage-views.csv

• tmp/cdbpkg_schema_coverage-tables.csv

• tmp/cdbpkg_schema_coverage-columns.csv

Mit Option -f reparieren, aber vorher Komponentenarchitektur lesen!!!

config -- check & repair

Komandozeile gibt guten Überblick über alles

$ cdbpkg check
...
cs.tools.batchoperations
------------------------
masken: name=cdbbop_operation/owner=public/attribut=button_ex...
  error: Referenced object does not exist
  reference: Icons
  foreign keys: {u'string1': u'foofoo'}
...

Reparieren einfacher im CDB-Client / je Modul :

Kontextmenü Modulkonfigurationsüberprüfung

Updates & Konflikte

Source-Code

Konflikte im SCM-System ermitteln & auflösen

Konfiguration + Schema

Konflikte in CDB ermitteln & auflösen .. CDB 10.x unter Protokolle .. CDB 15.x Modul / Entwicklerübersicht

Konflikte in Schema & Konfiguration kann CDB nur erkennen, wenn das DB Schema im Data Dictionary ist und die Konfigurationen den Modulen zugeordnet sind – siehe Voraussetzungen

was sind Updates?

DB + configuration + Source-Code sind EINS

Ändert sich daran was, ist das ein Update – Voraussetzungen

Entwicklung tauscht Patches im SCM-System aus

pull eines Patches aus dem SCM-System in das working directory aktualisiert configuration und Source-Code (das Update). cdbpkg sync spielt Änderung in DB ein

cdbpkg & SCM / big picture

Transport Source-Code & Konfiguration

\---cust.plm             # CDB-Paket
    ...
    \---cust             # Python Namespace 'from cust import foo'
        ...              # Python Pakete ...
        \--foo           # Python Paket 'foo'
           |  module_metadata.json
           +---configuration
           \---resources

• Source-Code: sind die Python Pakete wie z.B. foo. Diese werden mit dem SCM gemerged.

• Konfiguration: ist im Ordner configuration. Der Ordner muss mit cdbpkg diff und cdbpkg patch gemerged werden.

Merge Source-Code & Konfiguration

Typisches Schaubild für einen Feature-Branch, der in den master Branch gemerged wird. Der master Branch kann z.B. QS oder PROD sein. Egal ob man eine Kopie anlegt oder dazu ein SCM-System nutzt, es gibt immer einen Branch-Point und einen Merge-Point. Die Änderungen in der DB können nur mit cdbpkg gemerged werden.

Merge und Commit der Konfiguration

Diff zur Kopie des Branch-Point (Abzweigung) bilden:

$ cdbpkg diff cust.plm -p ./branch-point-copy -d ./patch_folder

Merge-Point: Patch in DB des PROD-Systems einspielen:

$ cdbpkg patch ./patch_folder/patch_cust.fo_xx_yyyy

Konflikte in CDB auflösen, anschließend commiten

$ cdbpkg build cust.plm               # DB export
# git add --all .                     # SCM-Commit
$ git commit -m "merged branch 'foo'" # ..
$ cdbpkg commit cust.plm              # CDB-Commit

CDB & SCM-System

• Transport des Source-Code über SCM-System.

• Paket cust.plm wird im SCM-System versioniert. Besteht aus Source-Code + configuration

• Abgleich zw. DB & configuration machen die cdbpkg -Tools

• cdbpkg -Tools und SCM-System müssen synchron verlaufen (siehe Merge-Schaubild)

• Einfach mal ins SCM committen ist vorbei! wer das pull‚t hat u.U. ein bisect Problem

Wahl des SCM-System

prinzipell geht jedes, populär sind SVN & git

Verglichen mit SVN ist git beim Branchen und verteiltem Arbeiten wesentlich stärker. Z.B. diverse Protokolle zum Transport: file://, http://, ssh:// usw. / s.a. git URLs, git-send-email

nicht zu vergessen: SVN ist tot.

Wir verwenden hier git / siehe auch get git started

SCM-System einrichten

(prod)$ cd cust.plm
(prod)$ git init
(prod)$ git add --all .
(prod)$ git commit -m 'cust.plm initial'

Ggf. letzte Änderungen beenden und festschreiben

(prod)$ cdbpkg build cust.plm
(prod)$ git add --all .
(prod)$ git commit -m "add 'cust.foo' to package 'cust.plm'"
(prod)$ cdbpkg commit cust.plm

Merge Strategien

SCM-Systeme wie git verfügen über ausgereifte Merge Strategien zum Mergen von Source-Code (build-in).

Merge der CDB-Konfiguration benötigt besondere Strategie.

Diese Strategie bedarf cdbpkg Tools, welche die Semantik der Konfiguration kennen und Checksummen neu berechnen können.

Merge Strategie (git)

git unterstützt alternative Merge Strategien, mittels Git Attributen kann die Strategie individuell gewählt werden.

Um configuration nicht zu mergen; Strategie ours.

# location: cust.plm/.gitattributes
# CDB 15.x
cust/*/configuration         merge=ours

Dummy handler true für ours registrieren

$ git config --local merge.ours.driver true

Lieferantenanbindung

Lieferantenanbindung erfolgt an einem Branch-Point (foo). Die Auslieferung an den Lieferanten ist ein Clone. Siehe auch Releasemanagement und CONTACT Elements.

Änderung einplanen (master)

Initial gibt es den master branch, darin existiert bereits Modul cust.foo im Paket cust.plm. In dem Modul soll nun noch die Klasse Foo konfiguriert & implementiert werden.

$ git branch -v
* master 268a44e add 'cust.foo' to package 'cust.plm'

feature branch ‚foo‘ anlegen

$ git branch -v
  foo    268a44e add 'cust.foo' to package 'cust.plm'
* master 268a44e add 'cust.foo' to package 'cust.plm'

Siehe auch Releasemanagement und CONTACT Elements.

Änderung beauftragen (clone)

Der Übergabepunkt einer Beauftragung ist der Branch-Point (foo). Er muss dem Auftragnehmer übergeben werden.

(dev)$ git clone file:///path/to/prod/cust.plm.git/
(dev)$ cd cust.plm
(dev)$ git checkout foo
Zu Branch 'foo' gewechselt

Für einen Spiegel beim Auftragnehmer – ggf. auch mit Nutzdaten – sind i.d.R. weitere Maßnahmen erforderlich. Meist wird initial die komplette Instanz ausgeliefert (z.B. ZIP des CADDOK_BASE am Branchpoint plus DB-Dump aber ohne Storage).

Spiegel einrichten

Auftragnehmer muss (Teil-) Spiegel-System einrichten.

Stand aus Branch foo in den lokalen Spiegel einspielen

(dev)$ cdbpkg sync
(dev)$ cdbpkg import_blobs    # falls DB-Dump verwendet wurde
(dev)$ cdbpkg commit cust.plm

Änderung implementieren (1)

Die Aufgabe wird in zwei Teil-Aufgaben aufgeteilt. Als erstes richtet der Entwickler das DB-Schema für das ‚foo‘ feature ein.

In der Entwickler-Übersicht den Dev-Build anstoßen. Doppel-Klick auf ‚Dev Patches‘ zeigt die lokalen Änderungen.

Änderung implementieren (1)

Schema soll erster Commit ins SCM werden

(dev)$ cdbpkg build cust.plm
(dev)$ git add --all .
(dev)$ git commit -m "configured 'foo' schema"

Dieser Teil-Änderung ist nun im SCM-System. Alle weiteren lokalen Änderungen sollen relativ zu dem Stand jetzt aufgezeichnet werden.

(dev)$ cdbpkg commit cust.plm

In der Entwickler-Übersicht ist der Eintrag ‚Dev Patches‘ für die lokalen Änderungen nun verschwunden.

Änderung implementieren (2)

Entwickler erstellt cust.plm/cust/foo/__init___.py

#!/usr/bin/env python
# -*- coding: utf-8; mode: python -*-

from cdb.objects import Object
class Foo(Object):
    __maps_to__   = "foo"
    __classname__ = "Foo"

und registriert den Voll qualifizierten Python Namen (FQN).

Änderung implementieren (2)

Änderungen sind abgeschlossen, zweiten Commit vorbereiten ..

(dev)$ cdbpkg build cust.plm

In der Entwickler-Übersicht ist wieder der Eintrag ‚Dev Patches‘ zu sehen. Doppel-Klick darauf zeigt die lokalen Änderungen.

(dev)$ git add --all .
(dev)$ git commit -m "implemented class 'Foo'"
(dev)$ cdbpkg commit cust.plm

Umsetzung der Anforderung ist nun vollständig im SCM-System (Source-Code und Konfiguration) und kann ausgeliefert werden.

Änderung ausliefern (push)

Auslieferung erfolgt in den Übergabepunkt; Branch foo des Auftraggebers.

Änderung ausliefern

$ git push origin foo
...
[PATCH 1/2] configured 'foo' schema
[PATCH 2/2] implemented class 'Foo'

git ist – wie kein anders SCM-System – für dezentral und offline ausgelegt. Lösungen für offline Szenarien sind z.B. git-send-email oder git-bundle .. um nur zwei zu nennen.

Zusammenfassung Lieferantenanbindung

• Es muss einen reproduzierbaren Übergabepunkt (Gesammtzustand des Systems) geben. Hierfür eignet sich ein Branch.

• Es muss ein Spiegel beim Lieferant aufgebaut werden. I.d.R. wird man nie alle Dienste und Funktionen auf dem Spiegel einrichten (zu Aufwendig).

• Lieferant plant die Implementierung, setzt sie um, testet sie und liefert sie wieder an den Übergabepunkt aus.

Bisher nicht betrachtet, wie bekommt der Auftrageber die Änderung in seinen master? Dazu siehe auch Releasemanagement und CONTACT Elements.

Entwicklungszweige mergen

Merge ist immer gleich

Der Merge des Branch foo enspricht genau dem Merge-Schaubild. Es gibt den Branch-Point und im Merge-Point sollen die Änderungen aus Source-Code (git merge) und Konfiguration (cdbpkg) im master Branch zusammengeführt werden.

Merge Strategie (cdbpkg diff)

Für den diff wird der Working-tree des Branch-Points benötigt.

$ git worktree add /tmp/foo-start 268a44e
$ git worktree list
  /path/to/cust.plm    3e3838e [foo]
  /tmp/foo-start       268a44e (detached HEAD)

Der Branch-Point 268a44e wurde aus dem Log entnommen. Die Kopie des Branch-Points liegt nun unter /tmp/foo-start.

Merge Strategie (cdbpkg diff)

Branch foo wird ausgecheckt, jetzt diff zum Branch-Point ermitteln

$ git checkout foo
$ cdbpkg diff cust.plm -p /tmp/foo-start -d /tmp
Writing changes to directory /tmp/patch_cust.fo_xx_yyyy
11 changes on cust.foo
 1 changes on cust.plm

Der Patch liegt jetzt bereit unter …

$ dir /tmp/patch_cust.fo_xx_yyyy

Die Vorbereitungen sind damit abgeschlossen, der eigentliche Merge (SCM-Merge + cdbpkg patch) kann nun beginnen.

Merge foo into master

SCM-Merge für Source-Code & cdbpkg patch für Konfiguration

$ cd cust.plm
$ git checkout master
$ git merge foo                               # SCM-Merge
$ cdbpkg patch /tmp/patch_cust.fo_xx_yyyy     # CDB-Merge

Konflikte in CDB auflösen, anschließend commiten

$ cdbpkg build cust.plm
$ git add --all .
$ git commit -m "merged branch 'foo'"
$ cdbpkg commit cust.plm

Zusammenfassung Merge

• Source-Code wird vom SCM-System gemerged.

• configuration benötigt andere Merge Strategie

• Um Konfig-Änderungen zu mergen, muss der Start-Punkt reproduzierbar sein. Hierfür eignen sich die Branch-Points.

• Der master war exemplarisch, i.d.R. wird man für den master min. zwei Branches haben: QS und PROD

• Der Transport zw. QS und PROD ist wieder vergleichbar, nur mit anderem Branch-Point und Merge-Point.

Merge ist immer gleich

Für die Umsetzung eines Features (einer Anforderung) gibt es den Feature-Branch. Im Merge-Point werden die Änderungen aus Source-Code (git merge) und Konfiguration (cdbpkg) im master Branch zusammengeführt werden.

Danke!

Marken- & Produktnamen