workflow.md

# Workflow

This toolkit is maintained in a GitLab group,
hosted on the [M4Lab's][m4lab] [Transfer-Portal][tr-portal] [GitLab instance][tr-gitlab].  
Source code for for each part is managed in its own repo in this group.

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

!!! danger "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 individual 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

!!! tip "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

!!! tip "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`.

!!! tip "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][conv-comm] specification in this repository,
to auto generate a changelog with [conventional-changelog][conv-change].

### 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`.

## 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](#gitgitlab).

If not, make sure your machine is setup according to the [setup guide][setup-guide].

### Change/Create an existing/new functionality

- make your changes
- make sure all unittests still pass
- commit your changes following the [Git/GitLab](#gitgitlab) workflow defined.

## Documentation

Documentation for the toolkit is done entirely in Markdown
and rendered through MkDocs to a Website.
Each repository global `README.md` just points to the deployed documentation.
The same applies for the `CONTRIBUTING.md`.  
`CHANGELOG.md` and `LICENSE.md` are kept additionally directly in each repo.

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][mat-mkdocs-ext-ref].

To make any kind of diagram, sketch or similar,
use [PlantUML][puml].
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"
    ```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
    ```

## Schedule a release

For releases this project uses [standard-version][std-ver].
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][semver] 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 toolkit uses CI pipelines for

- publishing backend server and runner docker images to DockerHub
- deploying this pages-documentation

[conv-comm]: https://www.conventionalcommits.org/en/v1.0.0/
[conv-change]: https://github.com/conventional-changelog/conventional-changelog
[m4lab]: https://www.hft-stuttgart.de/forschung/innovative-hochschule-m4-lab
[mat-mkdocs-ext-ref]: https://squidfunk.github.io/mkdocs-material/reference/abbreviations/
[puml]: https://plantuml.com/
[setup-guide]: /contribute/machine-setup.html
[semver]: https://semver.org/
[std-ver]: https://github.com/conventional-changelog/standard-version
[tr-gitlab]: https://transfer.hft-stuttgart.de/gitlab/explore/projects
[tr-portal]: https://transfer.hft-stuttgart.de/