Hinweise zum Umzug von Device Access von SVN nach Git

Note that meanwhile the entire Device Access software has been moved from SVN to Git. Do not use SVN any more!

Und sorry für den englisch-deutschen Mischmasch!

Inhalt

1 Repository Structure of SVN and Git

1.1 Actual Structure in SVN

If the complete trunk has been checked out, the workspace has the same structure as the SVN repository.

Repository (and fully structured workspace) (*) (%)
    ecm (+)
    eqdrivers (%)
        lxivicp (+)
        ...
        uiocslits (+)
    eqmodels (%)
        bc (+)
        bcu (+)
        ... (+)
        fg (+)
        ... (+)
        pz (+)
        ... (+)
        std (+)
        ... (+)
        vvc (+)
    fecs (%)
        k1xcg01 (+)
        k1xcg02 (+)
        ... (+)
        vmla07 (+)
    framework (+)
        ...
        devacc_java (#)
        ...
    hosts (+) 
    localdb
        dbd (+)
        dbsgen (+)
        polynomials (+)
    tests (+) (no tags yet)
    utilities (%)
        code-generation (+)
        devscr (+)
        PropHelper
            eqmodwrappers (+)
            PropHelper (+)
        uti (+)
        utiasl (+)
        utipy (+)
        utivme (+) 

• An asterisk (*) means that the directory has a trunk/branches/tags substructure.
• A percent (%) means that the workspace directory should contain an additional pom.xml to generate all its submodules.
• A plus sign (+) means that the Subversion devacc/tags substructure contains the version subdirectories like .../dgx/10.00.09.
• A hash (#) means that the project 'devacc_java' is built independently of the rest of the project 'framework'.

1.2 Structure for Git

Gitea does not support structuring. All modules are on the same level. Each module is a Git repository. Only the local workspace may be structured by cloning the Git repositories into the appropriate directories.

If a complete Maven reactor build should be possible, the local workspace has to be structured according to chapter 1.1 Actual Structure in SVN. If a workspace has been structured that way then the following applies:

• An asterisk (*) has no meaning for Git. Git has no trunk/branches/tags substructures.
• A percent (%) means that the workspace directory should contain an additional pom.xml to generate all its submodules. See ~hechler/devacc/supplements/help-module-poms.txt.
• A plus sign (+) means that the project is a stand-alone repository in terms of Git.
• A hash (#) means that the project 'devacc_java' is and should still be built independently of the rest of the project 'framework'.
  • Note that Vitaliy is testing Glassfish for Java 11 as a replacement for the current Java CORBA interface.
  • If 'devacc_java' is still necessary, which is probably the case for a while, it shouldn't be a module of the 'framework' any more but rather a stand-alone project.

Some equipment models are by now obsolete, like fg and pzs. Nevertheless, they should also be moved to the Git repository.

1.3 Open Issues

There are two additional elements in SVN which are not included in the Actual Structure in SVN above: misc and sys68v08.

1.3.1 misc

• The beamAdjustingKnob was meant as a replacement for the old HKR poti boards. Obsolete?
• The RT-kernel microc was meant as a replacement for pSOS+ on SEs. Since we plan to migrate ECM and EQMs to the LM32, it could be good to keep some examples that show how we did it last time.

Better move these elements to Git!

1.3.2 sys68v08

• The common, cxx, error, and psos directories under sys68v08/inc68 are old. They are now (since years) located under framework/header/incvme/src/m68k.
• Also all header files in sys68v08/inc68 are old and now located in framework/header/incvme/src.
• The elements download, eth, and mops are obsolete and can be ignored.
• The elements ufcclient, ufcdirect, and ufctest are also obsolete.

  ufclient

  UfClnt, der Userface-Client, stellt einer Anwendung die Möglichkeit zur Verfügung Gerätezugriffe durchzuführen auf Rechnern, die kein Kontrollsystem laufen haben, wo also direkte Gerätezugriffe via Userface nicht möglich sind. UfClnt kommuniziert mit dem Userface-Server (der zur Zeit nur auf AXP702 läuft), welcher die Gerätezugriffe via Userface durchführt.

  ufcdirect

  Direct Userface access for C++ applications (on AXPs? with VMS). Replaced by UFCReloaded.

  ufctest

  Userface tests with Fortran test applications.

So, I guess, sys68v08 isn't necessary any more. Should it be moved to Git anyway?

2 Convert an SVN Project into a Git Project

Hier exemplarisch ein Kommando, um ein Projekt aus dem SVN-Repository in ein Git-Projekt im Workspace zu konvertieren:

git svn clone https://www-acc.gsi.de/svn/devacc -A author-file.txt \
              -T trunk/eqmodels/bc/ -t tags/eqmodels/bc/ --prefix=svn/ bc

Die Pfad-Angaben für -T und -t hängen davon ab, was genau man als Git-Projekt betrachtet. In der Regel gilt, dass jedes Modul, das unabhängig released (getagged) werden kann, also eine eigene Versionsnummer hat, in Git ein eigenes Projekt ist. Das ist:

• das gesamte framework,
• jedes Gerätemodell (im Beispiel-Command oben bc),
• jeder Gerätetreiber,
• jeder FEC,
• usw.
• Siehe auch die angedachte Repository-Struktur in Kapitel 1.3.

Das genaue Ziel-Verzeichnis hängt davon ab, wie man seinen lokalen Workspace gestaltet - flach oder strukturiert. Für einen kompletten sogenannten 'reactor build' in Maven benötigt man allerdings die in Kapitel 1.3 angegebene Struktur in seinem Workspace. Siehe dazu Kapitel 2.1 First Tests unten.

Eine Zeile im Author-File sieht z.B. so aus

hechler = Ludwig Hechler <L.Hechler@gsi.de>

wobei hechler der Linux-Username ist. Git nutzt das, um richtige Namen als Author zu speichern und nicht den kryptischen Linux-Username. Man kann natürlich auch für mehrere Linux-Usernames den selben Author angeben, also z.B.

hechler = Ludwig Hechler <L.Hechler@gsi.de>
lhech = Ludwig Hechler <L.Hechler@gsi.de>

Siehe ebenfalls die Links in Kapitel 5.1 Von SVN nach Git

Anzeigen des GIT-Projektes als Baumstrucktur:

git log --pretty=format:'%Cred%h%Creset %C(bold blue)<%an>%Creset%C(yellow)%d%Creset %Cgreen(%cr, %cd)%Creset%n%w(80, 8, 8)%s' --graph --all

Das legt man der Einfachheit halber mit einem Alias in .gitconfig fest.

Updaten von SVN nach Git, falls in SVN noch was eingecheckt wurde und man sein (lokales) Git-Repository aktualisieren möchte:

git svn fetch
git branch -r
  svn/tags/10.00.01
  svn/trunk
git merge svn/trunk

Siehe auch Kapitel 2.6 Update Git Project when SVN has Changed

Updaten von Git nach SVN (quasi rückwärts), falls das mal nötig wäre:

git commit -m "message"  # Änderungen erst ins lokale Git-Repository...
git svn dcommit          # ...und von dort ins remote SVN-Repository

2.1 First Tests

Einen Workspave mit allen vier Gerätetreibern, drei Gerätemodellen, einem PPC- und einem uIOC-FEC, dem kompletten Framework, der Host-Software, der kompletten localdb, den 'misc'-Modulen beamAdjustingKnob und microc, dem neuen Projekt supplements (siehe Kapitel 3 Additional pom.xml), einigen 'tests' sowie einigen 'utilities' gibt es schon bei Ludwig, siehe ~hechler/devacc/.

Generierungen mit mvn compile sind durchgelaufen. Vorher wurde ein Komplettlauf (reactor build) mvn clean install auf ~hechler/workspace/ (hier liegen die SVN-Originale) durchgeführt, um das lokale Maven-Repository (unter ~/.m2) auf den aktuellen Stand zu bringen, was aber eigentlich nicht nötig sein sollte.

Die Tags <scm> in den pom.xml sind auskommentiert und müssen noch auf das (nun bei GSI installierte) Versionsverwaltungssystem Gitea angepasst werden. In ~hechler/devacc, ~hechler/devacc/eqdrivers, ~hechler/devacc/eqmodels, und ~hechler/devacc/fecs/ gibt es pom.xml, die alle jeweils darunter liegenden Module enthalten, aber (noch?) nicht Teil der Versionsverwaltung mit Git sind (ob und wie das geht, weiß ich noch nicht).

Die Directory-Struktur sollte am Ende so aussehen, wie oben in Proposed structure for Git angegeben, hängt aber anscheinend auch am gewählten Versionsverwaltungssystem. Je ein eigenständiges Git-Projekt (im Workspace) wäre dann

• ~hechler/devacc/framework
• ~hechler/devacc/hosts
• ~hechler/devacc/eqdrivers/uiocslits
• ~hechler/devacc/eqmodels/bc
• ~hechler/devacc/eqmodels/std
• ~hechler/devacc/fecs/ke1cg03
• ~hechler/devacc/utilities/PropHelper/PropHelper
• ~hechler/devacc/utilities/PropHelper/eqmodwrappers

Hier noch die zusammengestellten Kommandos mit denen der Git-Workspace erstellt wurde, wobei ${myroot} das gewünschte Wurzelverzeichnis ist.

Achtung, nach --prefix=svn/ kommt immer (mindestens) ein Blank!

cd ${myroot}
mkdir devacc
cd devacc
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/framework -t tags/framework --prefix=svn/ framework

cd ${myroot}/devacc
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/hosts -t tags/hosts --prefix=svn/ hosts

cd ${myroot}/devacc
mkdir eqdrivers
cd eqdrivers
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/eqdrivers/uiocslits -t tags/eqdrivers/uiocslits --prefix=svn/ uiocslits

cd ${myroot}/devacc
mkdir eqmodels
cd eqmodels
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/eqmodels/bc -t tags/eqmodels/bc --prefix=svn/ bc
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/eqmodels/std -t tags/eqmodels/std --prefix=svn/ std

cd ${myroot}/devacc
mkdir fecs
cd fecs
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/fecs/ke1cg03 -t tags/fecs/ke1cg03 --prefix=svn/ ke1cg03

cd ${myroot}/devacc
mkdir -p utilities/PropHelper
cd utilities/PropHelper
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/utilities/PropHelper/PropHelper -t tags/utilities/PropHelper/PropHelper --prefix=svn/ PropHelper
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/utilities/PropHelper/eqmodwrappers -t tags/utilities/PropHelper/eqmodwrappers --prefix=svn/ eqmodwrappers

cd ${myroot}/devacc/utilities
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/utilities/code-generation -t tags/utilities/code-generation --prefix=svn/ code-generation
git svn clone https://www-acc.gsi.de/svn/devacc -T trunk/utilities/devscr -t tags/utilities/devscr --prefix=svn/ devscr

Mittlerweile (4. März 2019) sind weitere Projekte auf Git umgestellt (aber noch nicht in Gitea). Siehe ~hechler/devacc.

2.2 Script for Automatic Migration from SVN to Git

Andreas Schaller hat das Script git_migration.sh entwickelt, das die Migration von SVN nach Git komplett automatisiert. Man muss sich das Projekt GitMigrationScript aus Git clonen und kann es direkt nutzen, siehe ~hechler/git/GitMigrationScript. Aber Achtung, das Script läuft nur auf acc7! Das Git auf acc6 ist zu alt. Hilfe bekommt man mit ./git_migration.sh --help oder von Andreas.

Ich habe das Script in ein eigenes Script integriert und damit in einem Lauf alle Gerätemodelle aus SVN geholt und lokal als Git-Projekt sowie im Gitea-Repository angelegt, siehe ~hechler/devacc/eqmodels/clone-eqmodels-from-svn.sh. Hier ein Auszug dieses Scripts:

#! /bin/bash

EQMODELS="""
bc
bcu
...
...
ug
void
vvc
"""

if [ "$(uname -n | cut -c -5)" != "asl74" ]; then 
    echo "Script works on asl74x only!"
    exit 1
fi

cd ~/devacc/eqmodels

for eqmodel in ${EQMODELS}
do
    echo "----- ${eqmodel} ----------"
    ~/git/GitMigrationScript/git_migration.sh --project ${eqmodel} --gitProject eqmodel_${eqmodel} --svnGroup devacc --organization devacc --svnPath eqmodels --svnLayout=rootTTB --remoteHost origin
    mv eqmodel_${eqmodel} ${eqmodel}
    pushd ${eqmodel}
    sed -i \
        -e "s|scm:svn:https://www-acc.gsi.de/svn/devacc/trunk/eqmodels/|scm:git:ssh://git@git.acc.gsi.de/devacc/eqmodel_|g" \
        -e "s|</developerConnection>|.git</developerConnection>|g" \
        pom.xml
    grep -v "<tagBase>" pom.xml > pom.xml.tmp
    mv pom.xml.tmp pom.xml
    git commit -a -m "Ready for production"
    git push
    popd
done 

Das Script passt zusätzlich das pom.xml an: Es wird die <developerConnection> von der SVN- auf die Git-URL umgestellt, die Definition der <tagBase> entfernt und die Änderung ins Gitea-Repository gepushed. Siehe dazu auch das folgende Kapitel.

2.3 Update pom.xml to use Git

To use Git instead of SVN when using Maven to generate and release software, the project pom.xml needs a new SCM URL.

Old SVN URL:

  <scm>
    <developerConnection>scm:svn:https://www-acc.gsi.de/svn/devacc/trunk/<myproject></developerConnection>
  </scm>

New Git URL:

  <scm>
    <developerConnection>scm:git:ssh://git@git.acc.gsi.de/devacc/<myproject>.git</developerConnection>
  </scm>

The <tagBase> definition in the project pom.xml was necessary since in Device Access we had the trunk/tags/branches on top of the SVN repository. So the line

<tagBase>https://www-acc.gsi.de/svn/devacc/tags/<myproject></tagBase>

must be removed from pom.xml.

2.4 Access to the Repositories

It's probably the best to test the deployment to the Git and Nexus repositories with the project fecs/kp1cg25.

• Try a git push first to check if you have write access to the Git server (gitea).

• Then try a mvn deploy with a snapshot version to check if you have write access to Nexus.

• If both accesses work, try a full release with mvn release:prepare and mvn release:perform.

See SSH Agent and ACC Authentication in IN's Wiki.

2.4.1 Inconsistency after Maven release

Im Moment (März 2019) gibt es eine Inkonsistenz nach der Ausführung von mvn release:prepare und mvn release:perform. Macht man danach nämlich ein git diff master origin/master, dann werden Differenzen u.a. zwischen dem pom.xml im master Branch und dem pom.xml im origin/master Branch gemeldet, was nicht sein sollte. Andreas Schaller führt das im Moment auf einen Bug in Maven zurück.

Um das wieder glatt zu ziehen, führt man danach einfach ein

git branch
* master

git pull

in seinem master Branch aus.

2.5 Create a Git Repository and Push Sources

Alle Kollegen in der Gruppe ACO/FEC (ehem. CSCOFE) haben Lese- und Schreibzugriff auf alle Repositories in der 'Organization' 'devacc'. Die Owner von 'devacc' sind Klaudia, Peter und Ludwig.

2.5.1 Create a Git Repository

Ein neues Repository legt man im Gitea-Browser an.

• Alle Device-Access-Software-Repositories sind in der "Organisation" "devacc" untergebracht.
• Im Dashbord rechts im Kasten Repositories [n] sollte man die schon bestehenden sehen.
• Rechts neben Repositories [n] das "*+*" klicken, um ein neues Repository anzulegen.
• Im neuen Fenster als Owner unbedingt devacc wählen, nicht seinen privaten Namen!
• Für den Repository Name gibt es Regeln für Prefixe:

  Repositories	Name	Beispiele
  Gerätetreiber	eqdriver_<eqdrv>	eqdriver_uiocslits
  Gerätemodelle	eqmodel_<eqmod>	eqmodel_bc
  Frontends	fec_<fec>	fec_ke1cg03
  Framework	framework	(ohne Prefix)
  Host-Software	hosts	(ohne Prefix)
  Lokale DB	localdb_<module>	localdb_dbd
  Verschiedenes	misc_<module>	misc_microc
  Ergänzungen	supplements	(ohne Prefix)
  Tests	tests	(ohne Prefix)
  Utilities	util_<utility>	util_utiasl
  		util_PropHelper_PropHelper
  		util_PropHelper_eqmodwrappers

• Für das Gerätemodell BC also eqmodel_bc angeben.
• Das 'Initialize Repository' hakt man für Device Access in der Regel nicht ab.
• 'Create Repository' klicken und fertig.
• Im aufgehenden Fenster unter "Clone this repository" den Button "SSH" wählen und das Fenster erst mal offen lassen.

2.5.2 Push Master Branch (former SVN trunk)

• Unter Linux (Konsole, Terminal) auf das Projekt-Verzeichnis wechseln Beispiel:

  asl733$ pwd
  /home/bel/hechler/lnx/devacc/eqmodels/bc

• Alle geänderten Quellen committen

  asl733$ git add pom.xml
  asl733$ git commit -m "Ready for production"

• und den Master-Branch pushen.

  asl733$ git remote add origin git@git.acc.gsi.de:devacc/eqmodel_bc.git
  asl733$ git push -u origin master

  wobei man sich die beiden Kommandos aus dem noch offenen Browser-Fenster unter "Pushing an existing repository from the command line" kopiert.

2.5.3 Push Tags (former SVN tags)

• Alle SVN-Tags sollten auch ins Git-Repository

  asl733$ git branch -a 
  * master
    remotes/origin/master
    remotes/svn/tags/10.00.00
    remotes/svn/tags/10.00.01
    remotes/svn/tags/10.00.02
    remotes/svn/tags/10.00.03
    remotes/svn/tags/10.00.04
    remotes/svn/tags/10.00.05
    remotes/svn/tags/10.00.06
    remotes/svn/tags/10.00.07
    remotes/svn/trunk

• Dazu ein kleines Bash-Script erstellen und die Liste der TAGS entsprechend obiger Liste anpassen, beispielsweise

  #! /bin/bash
  
  TAGS="""
  10.00.00
  10.00.01
  10.00.02
  10.00.03
  10.00.04
  10.00.05
  10.00.06
  10.00.07
  """
  
  for tag in ${TAGS} 
  do
      git checkout svn/tags/${tag}
      git tag "${tag}" -m "Save SVN tag"
      git push origin ${tag}
  done
  
  git checkout master

• Das Script evtl. noch ausführbar machen (chmod u+x tag.sh) und ausführen.
• Fertig

Möchte man einige alte SVN-tags aus seinem lokalen Repository löschen, dann geht das mit

git branch -rd svn/tags/10.00.00
git branch -rd svn/tags/10.00.01
...

2.6 Update Git Project when SVN has Changed

Wenn bereits ein Git-Projekt existiert, das aus SVN geclont wurde, und danach im SVN noch Änderungen committed wurden, geht man wie folgt vor, um die Änderungen auch ins Git-Projekt zu bekommen:

cd .../my-svn-project
edit myfile.cc
svn commit -m "Eine nachträgliche Änderung in SVN" myfile.cc

cd .../my-git-project
git status
# On branch master
git svn rebase
        M       myfile.cc
r3600 = effcb3cfd7dbfbc2b1a4c766697f49a09b1432e1 (refs/remotes/svn/trunk)

3 Additional pom.xml

Da das Git-Repository eine flache Struktur hat, also alle Projekte (bzw. Repositories) auf einer Ebene liegen, checkt man die einzelnen Projekte entsprechend so aus, dass man (wenigstens) in seinem lokalen Workspace die gewünschte Struktur hat.

Dann sind aber einige für einen "reactor build" notwendigen pom.xml, z.B. das oberste im Workspace oder das in eqmodels, nicht im Repository. Dazu habe ich ein neues Projekt namens supplements erfunden, das diese pom.xml enthält, die man dann in das entsprechende Directory kopieren oder dort verlinken (symlink) kann. Siehe dazu help-module-poms.txt in /home/bel/hechler/lnx/devacc/supplements/.

Übrigens: Diese pom.xml gibt es in SVN auch nur im trunk-Zweig. Zumindest mit der Standard-Maven-Methode (release:prepare, release:perform) können sie in SVN nicht getagged werden.

4 Script git-status.sh

Dieses Script, das in devacc/supplements beheimatet ist, durchsucht alle Unterverzeichnisse unter dem angegebenen oder dem aktuellen Verzeichnis und führt ein git status, ein git br -a und ein git tag in jedem Verzeichnis aus, das ein Git-Projekt ist.

5 Links

5.1 Von SVN nach Git

• Von SVN zu Git – Migrationsvorbereitung
• Migrating from SVN to Git
• Migrating Projects from SVN to Git
• Git Subversion cheat sheet

5.2 Git

• Git - Fast Version Control
• The Git Book (empfehlenswert!)
• Useful Git Commands
• The Ultimate Beginner Git Cheatsheet
• Git Cheat Sheet I
• Git Cheat Sheet II (PDF)
• Git Cheat Sheet III

5.3 Gitea

• Gitea Documentation