Workflow

This project is maintained in a GitLab repository, hosted on the M4Lab's Transfer-Portal GitLab instance.
Source code for the maven Java library and the markdown docs are managed together in a single repository.

This page tells you for the different parts of this project, how to do it.
The following applies project wide:

• language is english: code, comments, documentation, tickets, discussion, ...

Git/GitLab

disclaimer

There are a few rules any developer HAS TO follow, in order to get any chance his merge-requests will be accepted.

This project is managed using Git, hosted on the universities GitLab instance.

Issues/Merge Requests handling

Project management happens in the GitLab repositories issue board.

First of all, make sure for everything you do a ticket exists. Extending this, also check regularly your tickets are:

• assigned to you
• are in the correct column

There are three columns as of writing this documentation: To Do, Doing and review.
Planning something, a new ticket get's created and placed into the To Do column.

If you start to work on this ticket

• move it to Doing
• create a new feature branch from the master
  • named like: <ticket-id>-<some-descriptive-name>
• push the new branch
• create a new merge request
  • title starting with wip:
  • description containing closes #<ticket-id>
  • assign it to you (even if you're not able to merge)
• start working

After implementing your change

• move your ticket to review column
• change your merge requests labels: remove Doing and add review
• change assignee to someone to review your work

Branch Names

Branches should always start with the number of the related ticket, followed by a dash. This way the branch get's automatically shown in the ticket.

Committing

golden rules

• many small > few big commits
• unrelated changes in separate commit

We encourage everyone to make heavy use of git status and git diff. Please always check before committing, what exactly you have changed.
What we won't accept:

• whole file content removed and added back
  This most likely happens if you make great use of auto format, messing everything up. Another one error source is something changed line endings.
• empty lines containing spaces, or trailing spaces on line end (without technical reason)
  No big deal to fix, but time waste if we have to block your MR because of this.
• multiple changes in one commit, that have nothing to do with each other
  Great you have fixed a typo in a comment at the other end of the file. What do you think happens, if five people fix the same typo in their commits? We would have four merge conflicts, needing manual work to fix this mess. So create a new ticket for what you found, instead of just doing it as it doesn't hurt. It hurts, trust me.
• commit messages not following conventional commits specification

view diff of not yet tracked files

If you want to check a new file for flaws, sure git diff doesn't show anything. But you can add the file and before committing check with git diff --cached.

add only parts of changes in a file

As we want to have more small commits, than one single big one, it can be useful to split your changes into multiple commits, even inside the same file.
You can use git add -p [path|file]. This allows you to exactly decide which lines of your changes should be staged , before committing.

Commit Messages

We use the conventional commits specification in this repository, to auto generate a changelog with conventional-changelog.

Protected Branches/Tags

The repository has the master branch and release tags (format ^[0-9]+\.[0-9]+\.[0-9]+$) protected to project maintainers.

Branching-Model

We use a branch per feature based branching model. Base and target to merge is always latest master.

Java Development

First step before changing the source code, would be to check if there's something going on yet, or this topic possibly was discussed yet and abandoned for some reason. For this, check the defined GitLab workflow.

This library is a maven project. In order to contribute to it, make sure your machine is setup according to the setup guide.

Change an existing functionality

• check with the source structure below, where to find the part you want to change.
• make your changes
• make sure all unittests still pass
• commit your changes following the Git/GitLab workflow defined.

Add integration for new system

• familiarize with the code structure
• create a new package under de.hftstuttgart.unifiedticketing.systems, identifying the new system
• prepare to implement all abstract classes from the core package
  • class names have to be the same as the core ones, prefixed with the identifier you named your package after
• create unittests for the planned integration, either by putting a fail(); into each testmethod, or really writing tests first for TDD
• commit & push this skeleton-like state
• create WIP merge-request
• implement

Source code structure

After cloning the repository, you'll have to open/import an existing maven project in your IDE of choice. There WILL NOT be any configuration files for a specific IDE committed into the code. In regards to the maven project parts, only the pom.xml and the contents under /src are committed.

The main package for everything of this library is de.hftstuttgart.unifiedticketing.
Beneath it is split into three sub-packages:

subpackage	content
core	root classes defining lib core, generic public interface
exceptions	library own exceptions
systems	subpackage per system integration, implementation of abstract core-classes

core:
The majority of the classes are abstract ones. They define the generic interface available to the user of this lib. Logic identical for all system integrations are found in these classes.
Only few methods are really declared abstract, in most cases it's the part calling the external system.

exceptions:
The library defines its own exceptions, based on RuntimeException. If you throw any exception, only use exceptions from this package, never anything else.

If you miss an exception you'd like to throw, add a new one that extends UnifiedTicketingException.

systems:
Each system that's integrated into this lib, will have a sub-package under de.hftstuttgart.unifiedticketing.systems. In this very own package every abstract class from the core-package has to be implemented. Apart from that, every system can define as many helper classes or additional sub-packages.

Unittests

The logical code is structured under /src/main/java. For unittests the same package structure is created under /src/test/java. Tests are written using the jupiter-engine from JUnit5, combined with Mockito3.

• test-classes are named identical to the class under test, suffixed with Test
• test-classes have to be in the same package than the class under test

What has to be tested:

• constructors
• getters/setters
• calculations/transformations/...
• fluent-api to return the same instance
• serializing request data before request
• failing web-request
• successful web-request & deserializing of received data

testing external resources

All tests have to run offline. To test external resources, e.g. a web-request, use Mockito to block the code under test to really access the external resource and transparently return your mock answer expected for the assertions following.

test abstract classes

To test non-abstract code of abstract classes, you can instantiate a mock of it through Mockito, set to call the real methods:

instance = mock(ClassUnderTest.class,
    withSettings().useConstructor().defaultAnswer(CALLS_REAL_METHODS));

Documentation

Documentation for the project is done entirely in Markdown and rendered through MkDocs to a Website. The repository global README.md just points to the documentation root, which is /docs/index.md. The same applies for the CONTRIBUTING.md.
CHANGELOG.md and LICENSE.md are kept with content in project root, they are linked with a relative soft-link into the documentation folder.

Files related to the documentation:

path	description
mkdocs.yml	configuration file for mkdocs
requirements.txt	needed pypi packages to pass to pip for install
/docs/**/*	documentation files
/docs/index.md	Pages root

With the aim to give the documentation an appealing appearance, additional to the default markdown specification, a few extensions are enabled in the mkdocs config.
Please have a look at them and make use of, where it seems adequate. Reference for them can be found in the MkDocs-Material site.

To make any kind of diagram, sketch or similar, use PlantUML. You have to surround the PlantUML code with code fences, marked as plantuml as language identifier. Then they will be rendered into an svg on pages creation.

Example:

code

```plantuml
queue "write\nmarkdown" as write
queue "commit/push/\nmerge changes" as update
queue "pipeline\ntriggered" as cicd
queue "MkDocs\nMaterial" as MkDocsMat
queue "transpiled HTML\nonline" as deployed

write -right-> update
update -right-> cicd
cicd -right-> MkDocsMat
MkDocsMat -right-> deployed
```

result

Schedule a release

For releases this project uses standard-version. This generates an automatic changelog based on the commits and tags it. The version of the library has three numbers and has to follow the semantic-version scheme.

Tags marking a release have the format ^[0-9]+\.[0-9]+\.[0-9]+$. Pushing these tags is restricted in the GitLab Repo settings for maintainers only.
Pushing a release tag triggers the CI/CD release pipeline for the maven project.

CI/CD

This project uses GitLab-CI pipelines for

• publishing the maven library to the repository own package registry
• deploying this pages documentation

These pipelines are defined in several files:

file	content
.gitlab-ci.yml	root file, stages definition, include of other pipeline parts
.gitlab-ci-maven.yml	jobs regarding java library
.gitlab-ci-mkdocs.yml	jobs regarding pages documentation

pipeline graph overview:

These jobs are defined with the needs keyword, to make them only depend on exactly the needed previous jobs. This makes it possible to run docs and library pipelines in parallel, without waiting that all jobs of a stage must have finished before entering the next stage.

With the only keyword the trigger of these pipelines is optimized, to only run if necessary.
In general the final deployment jobs have configurations to run only on the secured branches/tags. Additionally all jobs are configured to only run, if changes on related files of this pipeline were made.