GitLab-MWT.md

+# GitLab -- The Minimum Working Tools And Their Usage.
+
+This is our best guess of good practices to start coding with.
+
+
+
+## Misc
+
+We use a git-flow-based workflow.
+
+
+
+## Mantras
+* If it is not an issue, it is not on the radar. If it is not on the radar, it is not worked on.
+* *Never* build a broken window into the house.
+
+
+
+## Commit
+Code must not be committed
+* if it does not build, or
+* if it does not pass all unit tests
+on the developer's local machine.
+**Exception:**
+Code on a feature branch may fail tests when explicitly labelled as *WIP*, eg, in order to pass code to colleagues.
+
+
+
+## Releases, Develop, Master
+
+*Develop* tracks the latest development state that is CI-tested.
+*Master* tracks releases that are CI-tested *and* manually verified.
+
+We *release* our software to our group via *master*.
+This happens frequently, on a regular basis.
+
+In contrast, *develop* integrates completed portions of functionality.
+
+
+
+## Milestones
+
+Milestones specify a certain functionality.
+They shall live on the order of 2 weeks.
+They consist of single actionable steps, aka issues.
+They are merged to develop only when completed.
+Consequently, Milestone = Feature Branch.
+
+A milestone must refer to a *functionality* issue (see there).
+Consequently, milestones cannot be created without prior discussion.
+
+We do not use the progress bar of a milestone.
+
+
+
+## Issues
+
+We need issue categories aka labels (plus the ones defining the boards' columns):
+* functionality
+* feature
+* deferred
+* bug
+
+*Functionality* issues ask for some functionality to be added.
+They are typically not acionable.
+They rather describe the functionality.
+The current ViSTA++ issues are good examples of *functionality* issues.
+They have to be discussed and voted for inclusion, exclusion, deferral by the team.
+On acceptance they create at least one milestone and their *feature* issues.
+
+*Features* are the actionable steps of a milestone.
+They amount to at most rather 2 than 5 hours.
+
+*Bugs* are descriptions of a malfunction; the expected and the actual behaviour; the OS, the compiler, etc.
+They are typically not acionable.
+The implicitly agreed-upon action related to a bug is "fix it".
+
+For *features* and *bugs* we might want to add to-do lists and use them as check lists, or reminders of the individual sub-steps to be taken.
+We might even come up with predefined best-practice checklists that are copied and pasted for certain situations.
+
+*Deferred* labels *functionality* issues that are voted to be discussed later.
+
+No new code may be written without first filing an issue for it.
+
+In order to track issues and to simplify merge requests, every commit addressing an issue has to name the issue in the commit message (3rd+ line).
+
+
+
+## Feature Branch
+
+Whenever new code -- due to issues and milestones -- is added to the code base in the develop branch, a feature branch is created.
+It is named by the milestone causing the branch to be spawned off of develop.
+Consequently, no new code can be written without first filing a functionality issue (or a bug report); and consequently not without prior discussion.
+
+A feature branch has to be closed via a merge request.
+
+A feature branch adresses only a single bit of functionality aka a milestone.
+
+*Note*: Feature branches must not grow too large, otherwise merges become infeasible.
+
+
+
+## Merge Request
+
+A merge request shall be filed whenever functionality is presumed to be finished, i.e., *all* tests pass on the developer's machine.
+The merge request shall then be examined for conflicts, tested, reviewed, and eventually merged.
+
+A merge request should be handled by people not involved in the development of the branch.
+Ideally, CI automatically checks if all tests pass and posts build results to the discussion board.
+
+A MR is merged by:
+* checking out the feature branch to be merged on a developer's machine
+* merging develop into the current feature branch without committing
+* build and test
+* fix
+* commit to feature branch
+* push feature branch
+* check CI
+* do code review
+* merge 
+
+
+## Closing issues
+
+Issues shall be automatically closed when they are released, i.e., merged into master.
+
+Use `closes #1` in 3rd+ line of commit message when functionality is considered complete.
+
+
+## Boards
+
+* *backlog* (GitLab's standard): 
+  * collects *functionality issues* issues and *bugs*
+* *discussion* 
+  * collects *functionality* issues that are under discussion whether they will be included/excluded/deferred.
+  * also collects *feature* and *bug* issues that need clarification in the regular meetings.
+* *iteration backlog*
+* *work in progress*
+  * collects those issues that are currently under development, i.e., for which a milesone and a feature branch exist
+* *ready for merge*
+  * collects those issues that are *presumed to be finished*, i.e., for which a merge request to develop exists.
+* *merged to develop*
+  * collects those issues that are already merged to develop, but not yet to master.
+* *closed* (GitLab's standard)
+  * collects those issues that are merged into master