Vor dem Schreiben der User Stories steht die Entscheidung, welcher
User Story Parser eingesetzt werden soll. Je nach gewählten Parser kann
sich das Format, in dem die User Stories verfasst werden, stark
unterscheiden. Das checkerberry-atdd-maven-plugin
bietet sowohl die Möglichkeit auf den bestehenden Standard-Parser
zurückzugreifen als auch die Verwendung einer eigenen
Parser-Implementierung. Wird eine eigene Implementierung gewählt, kann der
Benutzer beispielsweise selbst bestimmen, in welchem Format die User
Stories gespeichert werden.
Im Folgenden wird zunächst die Verwendung des Jira- und Standard-Parsers erläutert und anschließend auf die Implementierung eigener Parser genauer eingegangen.
Atlassian Jira ist ein Projektverfolgungstool für Teams. In diesem können Einträge (sogenannte Vorgänge) hinterlegt werden, die eine Aufgabe für den Entwickler beschreiben. Die Vorgänge bestehen unter anderem aus einem Vorgangstyp zur besseren Klassifizierung, einer Priorität für die Entwicklung, einer Beschreibung was entwickelt werden soll und benutzerbezogene Daten wie z.B. wer hat den Vorgang erstellt und wer soll ihn bearbeiten (siehe Abbildung 4.13, „Ein Vorgang in Jira“).
Der Jira Userstory Retriever kann die User Story Informationen, die für checkerberry business view benötigt werden, direkt aus den Jira Vorgängen auslesen.
Um den Jira Userstory Retriever nutzen zu können, muss Jira installiert sein und der Jira-REST-Service muss aktiv sein. Desweiteren benötigt man einen Benutzer in Jira, welcher Zugriff zu den benötigten Vorgängen besitzt. Es wird empfohlen, dass dieser Benutzer nur lesenden Zugriff auf Jira hat. Da der Jira-UserStory-Retriever seine Konfiguration während des build-Vorgangs von Maven bekommt, ist die Verwendung von Maven zwingend erforderlich.
Die nächsten Abschnitte beschreiben wie der Jira-UserStory-Retriever konfiguriert und eingesetzt wird.
Der Jira-UserStory-Retriever bezieht seine Konfigurationsdaten
während des build-Vorgangs aus der pom.xml von
Maven. Um ihn in das Projekt einzubinden, muss er über ein neues
Plugin in der pom.xml konfiguriert werden (siehe
Beispiel Maven-Konfiguration). Dort ist zu sehen wie das neue Plugin
eingefügt wird. Es handelt sich dabei um ein
checkerberry-atdd-maven-plugin welches in der Phase
analyze-tests ausgeführt wird. Als Abhängigkeit
wird der checkerberry-atdd-jira-userstory-retriever
angegeben. In dem Konfigurationsblock wird der JiraUserStoryRetriever
als Parserklasse definiert. Konfiguriert wird dieser dann in dem
properties-Block. Abschnitt 4.4.1.2, „Konfiguration des Jira-UserStory-Retriever“ geht
näher auf die Konfiguration des Jira-UserStory-Retrievers ein. Für
nähere Informationen zur pom.xml-Konfiguration,
siehe auch Abschnitt 4.3, „Konfiguration“.
Beispiel 4.4. Beispiel
<plugin>
<groupId>de.conceptpeople.checkerberry</groupId>
<artifactId>checkerberry-atdd-maven-plugin</artifactId>
<version>3.2.x</version>
<executions>
<execution>
<id>analyze-tests</id>
<goals>
<goal>analyze-tests</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>de.conceptpeople.checkerberry</groupId>
<artifactId>checkerberry-atdd-jira-userstory-retriever </artifactId>
<version>3.2.x</version>
</dependency>
</dependencies>
<configuration>
<parsers>
<parser>
<parserClass>
de.conceptpeople.checkerberry.atdd.jira.JiraUserStoryRetriever
</parserClass>
<properties>
[…]
</properties>
</parser>
</parsers>
</configuration>
</plugin>Die Konfiguration des Jira-UserStory-Retriever teilt sich in zwingend erforderliche Elemente und optionale Elemente. Die zwingend erforderlichen Elemente werden für eine erfolgreiche Verbindung zu Jira benötigt, die optionalen Elemente erlauben die Anpassung des Verhaltens. Fehlen die optionalen Werte, wird der Jira-UserStory-Retriever auf ein Standardverhalten zurückgreifen. Im Detail lassen sich folgende Elemente konfigurieren:
| Name | Erforderlichkeit | Beschreibung |
|---|---|---|
| url | Zwingend | Die Url des laufenden Jira-Servers, z.B. http://localhost:8080. |
| Name | Zwingend | Ein Jira-Benutzername, der zumindest lesende Rechte besitzt, z.B. user1 |
| Password | Zwingend | Das Passwort des Jira-Benutzers, z.B. password1 |
| projectNames | Optional | Eine Liste von Jira-Projektnamen, die beim Auslesen der Vorgänge berücksichtigt werden sollen. Mehrere Projektnamen werden mit einem Komma voneinander getrennt z.B. project1,project2,project3. Fehlt dieses Feld, werden alle Projekte berücksichtigt. |
| backlogSprint | Optional | Dieses Feld wird nur bei Jira-Agile benutzt. Wird die Sprint-Information aus Jira-Agile ausgelesen und der Vorgang besitzt keinen zugeordneten Sprint, so wird der Vorgang dem virtuellen Sprint Backlog zugeordnet. Der Name dieses virtuellen Sprints kann hier angepasst werden, z.B. NichtZugewiesen. |
| unknownSprint | Optional | Liegt kein Jira-Agile vor und es wurden keine Sprint-Informationen im Beschreibungstext hinterlegt, so wird der Vorgang dem virtuellen Sprint Unbekannt zugeordnet. Der Name dieses virtuellen Sprints kann hier angepasst werden, z.B. NichtZugewiesen. |
| issueType | Optional | Legt fest welche Vorgangstypen als User Stories interpretiert werden. Standardmäßig werden alle Vorgänge die den Jira-Vorgangstyp Story besitzen berücksichtigt. Das Verhalten kann an dieser Stelle angepasst werden, indem man z.B. den Typ Feature konfiguriert. |
Die entsprechenden Konfigurationseinträge werden in der
pom.xml des Projektes als properties-Unterpunkte
des plugins vorgenommen (siehe Abschnitt 4.4.1.1, „Konfiguration des Maven-Projekts“.).
Die Konfiguration Jira-UserStory-Retriever zeigt eine Beispielkonfiguration in dem alle Elemente gesetzt werden. Neben den Zugangsdaten wird das Verhalten so angepasst, dass nur die beiden Projekte ScrumDemo1 und ScrumDemo2 ausgelesen werden. Vorgänge, die in Jira Agile Sprint-Informationen besitzen, aber zu keinem Sprint zugeordnet wurden, werden automatisch dem Sprint Noch zu erledigen zugeteilt. Vorgänge welche keine Sprint-Informationen besitzen, werden dem Sprint Unzugeordnet zugeteilt. Als User Stories werden nur Vorgänge betrachtet, welche den Vorgangstyp Feature besitzen.
Beispiel 4.5. Konfiguration Jira-UserStory-Retriever
<plugin>
[…]
<configuration>
<parsers>
<parser>
<parserClass>
de.conceptpeople.checkerberry.atdd.jira.JiraUserStoryRetriever
</parserClass>
<properties>
<url>http://localhost:8081/</url>
<name>testUser</name>
<password>testPassword</password>
<projects>ScrumDemo1,ScrumDemo2</projects>
<backlogSprint>Noch zu erledigen</backlogSprint>
<unknownSprint>Unzugeordnet</unknownSprint>
<issueType>Feature</issueType>
</properties>
</parser>
</parsers>
</configuration>
</plugin>Der Jira UserStory Retriever benötigt für eine User Story eine Id, einen Namen, eine Priorität und Informationen über die Akzeptanztests. Beim Einlesen eines Jira-Vorgangs übernimmt der Jira UserStory Retriever die Id, den Namen und die Priorität vom Vorgang. Weiterhin wird die Information benötigt in welchem Sprint sich der Vorgang befindet. Liegt Jira Agile vor, kann diese Information aus dem Sprint-Feld des Vorgangs ausgelesen werden. Andernfalls muss diese Information im Beschreibungstext angegeben werden. Fehlt die Sprint-Information gänzlich, so wird der Vorgang einem virtuellen Sprint (Unbekannt) zugeordnet.
Der Jira UserStory Retriever liest standardmäßig alle Vorgänge eines Projekts ein, die den Jira-Typ Story besitzen (zur Anpassung dieses Verhaltens siehe Abschnitt 4.4.1.2, „Konfiguration des Jira-UserStory-Retriever“). Aus diesen wird dann der Beschreibungstext interpretiert. Finden sich in dem Beschreibungstext Informationen zu der Id, dem Namen, dem Sprint oder der Priorität, so haben diese Vorrang vor den Informationen die direkt aus dem Jira-Vorgang erhalten werden. Dies erlaubt es, die im Vorgang befindlichen Informationen zu überschreiben. Im Beschreibungstext können alle Informationen des Jira Vorgangs für checkerberry business view angepasst werden. Insbesondere sind dies:
Die User Story Id (@UserStory(“…“))
Der User Story Name (@UserStoryName(“…“))
Die Priorität (@Priority(“…”))
Der Sprint (@Sprint(“…”))
Auch werden hier dann die für die User Story nötigen Akzeptanzkriterien definiert. Das Format der Akzeptanzkriterien folgt dabei dem des Standardparsers. Für nähere Informationen dazu siehe Abschnitt 4.4.1.1, „Konfiguration des Maven-Projekts“.
Ein Beispielhafter Vorgang ist in Abbildung 4.14, „Wichtige Felder eines Jira Vorgangs“ zu sehen. Dort sieht man den Jira Vorgang mit der Id SD-2 und dem Namen Zweite Demo-Story. Der Vorgangstyp ist Story und die Priorität Kritisch. Für die User Story von checkerberry business view wird im Beschreibungstext der Name der User Story allerdings durch einen neuen Namen überschrieben (Ich möchte mich an dem System anmelden können). Außerdem wird dort der User Story ein Sprint zugeordnet (Der erste). Danach folgen die Akzeptanzkriterien. Dem Akzeptanzkriterium 2 (Hinzufügen eines Benutzers) ist dabei ein Akzeptanztest (AT2) zugeordnet.
Abbildung 4.15, „checkerberry ATDD Hudson Plugin“ zeigt unter anderem das Aussehen des in Abbildung 4.14, „Wichtige Felder eines Jira Vorgangs“ zu sehenden Vorgangs im checkerberry business view Plugin für Hudson. Aus dem Vorgang wurde die Story Id übernommen. Der zugeordnete Sprint und der Story Name wurden ebenso wie das Akzeptanzkriterium aus dem Beschreibungstext ausgelesen. In dem Beispiel gibt es in Jira insgesamt fünf Vorgänge, von denen drei in Jira als Story markiert sind und somit vom System erkannt wurden. Zwei davon wurden implementiert (Stories SD-1 und SD-2), der dritte (SD-4) muss noch implementiert werden.
