Merge branch 'main' into alm-code-reviews

docs/documentation/index.md

@@ -40,23 +40,41 @@ Dokumentenvorlagen wie das arc42-Template müssen nicht immer vollständig “au
 
 Darüber hinaus kann eine veraltete Dokumentation irreführend sein. Deshalb sollte in allen Dokumenten der Stand und eine Versionierung enthalten sein, um die Aktualität bewerten zu können.
 
+| BEST PRACTICE |
+|---------------|
+|Es sollte im Unternehmen geklärt werden, wie Dokumentation von Software erfolgen soll.|
+
 Innerhalb einer SAP-Systemlandschaft bietet der SAP Solution Manager Möglichkeiten zur Projektdokumentation. Die nachfolgenden Links bieten weitere Informationen dazu.
 
 WEITERE QUELLEN  
 1.	Das arc42-Template zur Architekturdokumentation, [Arc42-Template](https://arc42.org/download)  (aufgerufen am: 19.09.2024)
 2.	Stefan Zörner: Softwarearchitekturen dokumentieren und kommunizieren. Carl Hanser Verlag GmbH Co KG, 2021. ISBN: 978-3446469280
 
+## Dokumentation zur Versionsverwaltung
+
+### Transportauftrag
+Oftmals hilft es zum Transportauftrag zu dokumentieren
+* Ticketnummer und Titel des Tickets
+* Wichtigste Entwicklungsobjekte im Transport
+* Abhängigkeiten zu anderen Transporten (sofern vorhanden)
+* Kurzbeschreibung zu Änderungen im Transport
+Die Dokumentation zu jeder Aufgabe und zu jedem Auftrag während der Auftragsbearbeitung im Reiter "Dokumentation" zu erfassen. Die Dokumentation kann bis zur Freigabe laufend erweitert werden. Nach der Freigabe des Auftrags ist dies nicht mehr möglich.
+
+Diese Dokumentation auf dem Reiter "Dokumentation" kann man für jeden Transportauftrag erstellen, der ins Produktive Systeme geht. Transporte von Kopien sollte man nicht dokumentieren, um redundante Dokumentation zu vermeiden. Letztlich interessieren nur die Transporte, die ins Produktiv System gehen sollen, bzw. bereits gegangen sind.
+
+### Git-Client
+Sollte ein Git-Client wie abapGit oder gCTS eingesetzt werden, werden Code-Änderungen protokolliert. Zu jedem sogenannten Commit werden neben den Code-Änderungen noch Metadaten gespeichert. Zu den Metadaten zählen eine kurze Beschreibung, sogenannte Commit-Nachricht, Autor und  Datum. Die so entstehende Commit-Historie ermöglicht, vergangene Commits zu sehen und die Code-Änderungen nachzuvollziehen. Wird ein Ticket-System, wie zum Beispiel Jira oder Azure DevOps, für die Erfassung der Anforderungen benutzt, hat jede Anforderung an die Entwicklung eine eindeutige ID. Viele Teams haben die Vorgabe oder die interne Vereinbarung, diese ID in den Commit-Nachrichten einzutragen, damit sich die Commits den Aufgaben zuordnen lassen. Wird das konsistent gemacht, lassen sich mittels Freitextsuche in den Commit-Nachrichten alle Commits identifizieren, die zu einer bestimmten Aufgabe gehören. Das erleichtert wesentlich das Wiederfinden und die Überprüfung der Umsetzung im Fall von Bugs. Gleichzeitig lassen sich dadurch ähnliche Aufgaben sehr schnell umsetzen, weil die Entwickler das bereits funktionierende Beispiel finden und verfolgen können.
+
+| BEST PRACTICE |
+|---------------|
+|Wir empfehlen bei Änderungen, die ins produktive Systeme gehen egal ob mit Transportauftrag oder Git-Client mit Angabe was geändert wurde und mit Bezug zu einem externen Tool wie Ticketsystem|
 
 ## Dokumentation von Entwicklungsobjekten
 Neben Methoden, Funktionsbausteinen und Reports, die Dokumentation im Quellcode enthalten können, existieren weitere Entwicklungsobjekte im ABAP-System, die keinen Quellcode besitzen und daher auf anderem Weg dokumentiert werden müssen. Beispiele dafür sind:
 
 * DDIC-Objekte
 * Transaktionen
 
-| BEST PRACTICE |
-|---------------|
-|Wir empfehlen, für alle Entwicklungsobjekte und unabhängig vom Quellcode die Dokumentationsfunktion der ABAP-Workbench zu nutzen und die Aufgaben und Bedeutungen dieser Objekte im SAP-System zu dokumentieren. Hierbei sollte ausschließlich der Ist-Stand dokumentiert werden, gegebenenfalls angereichert um kurze Verweise auf die Änderungsdokumentation (Transportdokumentation, Defekt-Nummern).|
-
 Da die Workbench-Dokumentation auch an das Transportwesen angeschlossen ist, steht sie in allen Einzelsystemen einer Systemlandschaft zur Verfügung. Weiterhin kann diese Dokumentation von allen Benutzern eingesehen werden und wird für Reports vom ABAP-System automatisch in die Benutzeroberfläche eingebunden. Ein weiterer Vorteil kann darin bestehen, dass die Dokumentation mehrsprachig geführt werden kann. Auf SAP-Systemen mit SAP_BASIS >= 7.40 können im Quellcode ABAP-Doc-Kommentare verwendet werden. Dies kann als Alternative zur Dokumentation in der ABAP-Workbench verwendet werden. Der volle Funktionsumfang von ABAP-Doc-Kommentaren lässt sich derzeit allerdings nur mit den ABAP-Development-Tools für Eclipse ausschöpfen. Bei Verwendung von Core Data Services zur Definition von DDIC-Objekten können wesentlich mehr Entwicklungsobjekte im Quellcode dokumentiert werden und die Notwendigkeit externer Dokumentation entfällt. 
 Beginnend mit SAP NetWeaver 7.50 lassen sich die ABAP-Doc-Kommentare von Klassen und Schnittstellen als HTML-Dateien exportieren. Die SAP erweitert ihr Repertoire ab ABAP Plattform 7.55 um eine weitere Technologie zur Dokumentation von ABAP-Entwicklungsobjekten. Das Knowledge Transfer Document fokussiert sich auf die neuen Objekttypen, die primär aus dem ABAP Restful Application Programming Model (RAP) Kontext entstammen. Dieses umfasst unter anderem: CDS Views, Behavior Definitions, Service Definitions, Service Bindings, Annotation Definitions und Paket
 
@@ -81,15 +99,19 @@ Seit ABAP Plattform 7.55 gibt es das Knowledge Transfer Document. KTD kann für
 
 KTD müssen im selben Paket wie das Entwicklungsobjekt sein. Es wird nicht automatisch mit dem Entwicklungsobjekt transportiert, aber wenn das Entwicklungsobjekt gelöscht wird, wird auch das dazugehörige KTD gelöscht.
 
+| BEST PRACTICE |
+|---------------|
+|Wir empfehlen, für alle Entwicklungsobjekte und unabhängig vom Quellcode die Dokumentationsfunktion der ABAP-Workbench zu nutzen. Die Dokumentationsfunktion sollte in folgender Reihenfolge angewendet werden, je nachdem für welches Objekt welche Art von Dokumentationsobjekt verfügbar ist: 1. Knowledge Transfer Documents 2. abapDoc 3. Kurztexte Hierbei sollte ausschließlich der Ist-Stand dokumentiert werden, gegebenenfalls angereichert um kurze Verweise auf die Änderungsdokumentation (Transportdokumentation, Defekt-Nummern).|
+
 ## Dokumentation im Quellcode
 
 ### Dokumentationssprache
 
+Entwicklungsteams arbeiten heutzutage überwiegend international zusammen. Auch wenn Sie derzeit rein deutschsprachig entwickeln, kann Ihr Projekt im Laufe der Zeit internationalisiert werden. Der Aufwand, der dann durch Koordinationsprobleme oder sogar nachträgliches Übersetzen entsteht, steht in keinem Verhältnis zu dem vielleicht größeren Aufwand durch englische Dokumentation. Es hat sich außerdem gezeigt, dass die Lesbarkeit von Quellcode und Kommentaren durch englischsprachige Kommentare erhöht wird. Denn die ABAP-Befehle selbst sind englisch und im Stil von Sätzen aufgebaut. Der Leser des Quellcodes muss bei englischer Dokumentation also nicht ständig die Sprache wechseln.
+
 | BEST PRACTICE |
 |---------------|
-|Als Kommentierungssprache sollte Englisch verwendet werden.|
-
-Entwicklungsteams arbeiten heutzutage überwiegend international zusammen. Auch wenn Sie derzeit rein deutschsprachig entwickeln, kann Ihr Projekt im Laufe der Zeit internationalisiert werden. Der Aufwand, der dann durch Koordinationsprobleme oder sogar nachträgliches Übersetzen entsteht, steht in keinem Verhältnis zu dem vielleicht größeren Aufwand durch englische Dokumentation. Es hat sich außerdem gezeigt, dass die Lesbarkeit von Quellcode und Kommentaren durch englischsprachige Kommentare erhöht wird. Denn die ABAP-Befehle selbst sind englisch und im Stil von Sätzen aufgebaut. Der Leser des Quellcodes muss bei englischer Dokumentation also nicht ständig die Sprache wechseln.
+|Es sollte im Unternehmen geklärt, was die Kommentierungssprache ist. Die Empfehlung ist in englisch zu kommentieren.|
 
 ### Dokumentation von Änderungen
 Ab dem Zeitpunkt der Produktivsetzung eines Programms sollte darauf geachtet werden, dass Änderungen in Programmen angemessen dokumentiert werden. Hier ist das richtige Maß wesentlich: Eine vollständige Versionshistorie aller Änderungen und auskommentierter Quellcode reduzieren die Lesbarkeit des Quellcodes. Trotz dieses Nachteils dokumentieren einige Entwicklungsteams bewusst alle Änderungen im Quellcode, um die Fehlersuche auf Produktiv- oder Testsystemen zu vereinfachen, in denen die Versionshistorie nicht zur Verfügung steht. 
@@ -101,12 +123,16 @@ Ab dem Zeitpunkt der Produktivsetzung eines Programms sollte darauf geachtet wer
 ### Kommentare im Quellcode
 Kommentare im Quellcode sollen dazu dienen, Entwicklern das Verstehen des Quellcodes zu erleichtern, sofern dies nicht durch geschickte Gestaltung des Quellcodes allein (Modularisierung, Namenswahl von Methoden und Variablen) erreichbar ist.
 
-Kommentare sind für andere Entwickler und mit zunehmendem zeitlichen Abstand auch für den ursprünglichen Entwickler gedacht. Sie sollten die Frage beantworten, „Warum” etwas programmiert wurde und nicht „Was”. Letzteres ergibt sich aus dem Quellcode ohnehin, während die Beweggründe oft nicht klar erkennbar sind. Gerade sie helfen beim Verständnis aber wesentlich weiter. Dabei gilt der Grundsatz: So wenig Kommentar wie möglich, so viel Kommentar wie nötig.
+Kommentare sind für andere Entwickler und mit zunehmendem zeitlichen Abstand auch für den ursprünglichen Entwickler gedacht. 
 
 Stern-Kommentare sollten nur im Programmkopf oder für das temporäre Auskommentieren von altem Quellcode verwendet werden.
 
 Für alle anderen Kommentare empfiehlt SAP, Inline-Kommentare zu verwenden. Diese sollten jeweils vor dem Quellcode stehen, den sie dokumentieren, und genauso eingerückt sein wie dieser Quellcode. Letzteres wird (nur) für Inline-Kommentare auch vom Pretty Printer korrekt durchgeführt. 
 
+| BEST PRACTICE |
+|---------------|
+|Sie sollten die Frage beantworten, „Warum” etwas programmiert wurde und nicht „Was”. Letzteres ergibt sich aus dem Quellcode ohnehin, während die Beweggründe oft nicht klar erkennbar sind. Gerade sie helfen beim Verständnis aber wesentlich weiter. Dabei gilt der Grundsatz: So wenig Kommentar wie möglich, so viel Kommentar wie nötig.|
+
 WEITERE QUELLEN
 1.	Horst Keller, Wolf Hagen Thümmel: ABAP-Programmierrichtlinien. SAP Press, 2009. ISBN: 9783836212861
 

docs/open-source/open-source-projects.md

@@ -9,11 +9,10 @@ nav_order: 5
 ---
 
 {: .no_toc}
-
 # Vorstellung ausgewählter Projekte
 
 1. TOC
-   {:toc}
+{:toc}
 
 ## Übersicht
 

docs/testing/recommended-tools.md

@@ -13,29 +13,62 @@ nav_order: 3
 
 1. TOC
 {:toc}
+Die nachfolgend aufgeführten Testwerkzeuge sind nicht ABAP-spezifisch, sondern generell im Rahmen der (SAP)-Softwareentwicklung zu sehen. Das bedeutet auch, dass von Seiten des ABAP-Entwicklers (maskulin?) nichts beachtet werden muss, was die Tests in irgendeiner Weise, also weder positiv oder negativ, beeinflussen könnte.
 
-Die nachfolgend aufgeführten Tools (Testwerkzeuge?) sind nicht ABAP-spezifisch, sondern generell im Rahmen der (SAP)-Softwareentwicklung zu sehen. Das bedeutet auch, dass von Seiten des ABAP-Entwicklers (maskulin?) nichts beachtet werden muss, was die Tests in irgendeiner Weise (weder positiv oder negativ) beeinflussen könnte.
+Die Auswahl in diesem Leitfaden beschränkt sich auf die von SAP bereitgestellten(?) oder (schon) im Lizenzumfang enthaltenen Produkte. Daneben gibt es noch viele weitere Lösungen auf dem Markt, die für die ABAP-Entwicklung verwendet werden können.
 
-## SAP Cloud ALM
+## Testwerkzeuge im SAP Solution Manager
+--> Marco
 
-Als Nachfolgeprodukt des SAP Solution Managers, dessen Mainstream-Wartungsende seitens SAP auf Ende 2027 datiert ist, wurde für das Application Lifecycle Management (ALM, link zu diesem Kapitel) im Jahr xxx2018?xxx SAP Cloud ALM vorgestellt. Das Cloud-Produkt beinhaltet - wie auch der Solution Manager - unter anderem ein integriertes Testmanagement, das sowohl eigenständig (für manuelle Testfälle) als auch in Verbindung mit einer Testautmatisierungslösung wie Tricentis Test Automation (siehe den nächsten Abschnitt) eingesetzt werden kann. SAP Cloud ALM und damit auch dessen Testmanagement-Funktionen werden kontinuierlich weiterentwickelt.
+Der SAP Solution Manager (https://support.sap.com/en/alm/solution-manager.html // die Seite ist auf EN...) ist ein ausgereiftes System für das Application Lifecycle Management (ALM, Link zu diesem Kapitel), das unter anderem verschiedene Testwerkzeugen enthält.
+
+### Test Suite
+xxx...Standard SolMan
+https://help.sap.com/docs/SUPPORT_CONTENT/sm/3530264795.html
+
+### Test Steps Designer (oder das volle Programm hier?)
+xxx...aus FB... ST-OST Add-on
+https://support.sap.com/en/alm/focused-build.html
+https://support.sap.com/content/dam/support/en_us/library/ssp/alm/sap-solution-manager/focused-solutions/Focused_Build/sp14/FB%20-%20Test%20Management%20-%20L2%20SP14.pdf
+
+### CBTA
+xxx...Automatisierung...Standard SolMan
+https://help.sap.com/docs/SUPPORT_CONTENT/sm/3530264810.html
+
+## eCATT (extended Computer Aided Test Tool) --> gehört nicht unter "Testwerkzeuge im SAP Solution Manager" !!!
+xxx...
+Verwendung von eCATT irgendwie referenzieren auf eigenes Kapitel?
+https://help.sap.com/doc/saphelp_nw73ehp1/7.31.19/de-de/49/6d2fa0e0221ec6e10000000a42189b/frameset.htm
+oder https://help.sap.com/saphelp_gbt10/helpdata/DE/20/e81c3b84e65e7be10000000a11402f/frameset.htm ???
+
+## Testwerkzeuge in SAP Cloud ALM
+
+Als Nachfolgeprodukt des SAP Solution Managers, dessen Mainstream-Wartungsende seitens SAP auf Ende 2027 datiert ist, wurde für das Application Lifecycle Management (ALM, Link zu diesem Kapitel bzw. hab ich oben schon) im Jahr xxx2018?xxx SAP Cloud ALM vorgestellt. Das Cloud-Produkt beinhaltet - wie schon der Solution Manager - unter anderem ein integriertes Testmanagement, das sowohl eigenständig (für manuelle Testfälle) als auch in Verbindung mit einer Testautmatisierungslösung wie Tricentis Test Automation (siehe den nächsten Abschnitt bzw. Link dort hin) eingesetzt werden kann. SAP Cloud ALM und damit auch dessen Testmanagement-Funktionen werden kontinuierlich weiterentwickelt.
+
+--> Marco
+    Automatische Prozesstests mit CloudALM? (wie) geht das ? 
 
 ## Tricentis Test Automation
+--> Harald
 
-Tricentis ist ein eigenständiges Unternehmen, das nicht zu SAP gehört, aber durch eine (langjährige, tiefgehende?) Partnerschaft sehr gut in die SAP-Welt integriert und daher im SAP-Kontext die empfohlene Lösung zur Testautomatisierung ist (https://support.sap.com/en/alm/partners/test-automation.html).
+Tricentis ist ein eigenständiges Unternehmen, das nicht zu SAP gehört, aber durch eine strategische Partnerschaft sehr gut in die SAP-Welt integriert und daher im SAP-Kontext die empfohlene Lösung zur Testautomatisierung ist (https://support.sap.com/en/alm/partners/test-automation.html) / (https://www.tricentis.com/sap).
 
 ...verschiedene Ausprägungen...Lizenzen teilweise schon dabei...
         ·	Tosca: Integration in SAP SolMan – Link zu https://documentation.tricentis.com/tosca/2310/de/content/sap_solutionmanager/concept.htm 
         ·	TTA: Integration in SAP Cloud ALM – Link zu https://support.sap.com/en/alm/partners/test-automation.html 
 
-(Grafik, welches Tricentis-Tool für welches ALM-System etc.?)
+    §	Tool für automatische GUI-Tests über sämtliche Technologien (Webseiten, SAP GUI etc.)
+
+(Grafik selber machen auf deutsch, welches Tricentis-Tool für welches ALM-System etc., in Anlehnung an die Darstellung von SAP --> "Quelle...in Anlehnung an..."?) und die einzelnen Punkte kurz beschreiben
+![Clean Core](./img/tricentis_tools_uebersicht.png)
 
-(sollen wir auf 4 Ebenen gehen?)
-### Mögliche Einsatzszenarien
+### Mögliche Einsatzszenarien für automatisierte Testfälle
 #### Tägliche Smoke-Tests
+--> Harald
 Daily Smoke Tests in Testumgebungen...
 
 #### Regressionstests
+--> Harald
 Automatisierte Testfälle können hervorragend für Regressionstests in Prä-Produktionssystemen eingesetzt werden...
 was muss da beachtet werden???  
 Testdaten etc.?
@@ -48,15 +81,3 @@ SAP Application Lifecycle Management: Test Automation https://support.sap.com/en
 Tricentis: Die empfohlene Testlösungvon SAP https://www.tricentis.com/de/sap
 
 ----------------------
-/// Stichpunkte aus der Word-Datei ///
-
-o	Cloud ALM
-    §	?Automatische Prozesstests mit CloudALM? 
-        ·	Geht das ? 
-    §	Stand Sept 2024 laut Marco noch nicht gut nutzbar. ( freundlich formulieren ) --> ist das noch so?
-o	Tricentis: https://www.tricentis.com/de/sap
-    §	Hat erst mal mit ABAP-Entwicklung wenig zu tun, also da wäre nix zu beachten, aber als allgemeines Tool, um Software zu testen
-    §	Tool für automatische GUI-Tests über sämtliche Technologien (Webseiten, SAP GUI etc.)
-
-
-

docs/version-management/images

@@ -0,0 +1 @@
+