diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 8568d83c8199e4dd441d90ca446331331e7aef48..73698f50ddf52ff8d13828e8a08288768c353368 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -1,4 +1,14 @@ # Contribution Index -!!! todo - add contribution guides +To contribute to this project, +you first of all have to be a member of the University of Applied Sciences Stuttgart. +This project is hosted on our Transferportal's GitLab instance, +to which only HFT members have write access to. + +Apart from that, for contributing to the toolkit code itself, +you should be able to program in Java, or PHP. +For the documentation you need to have Python installed and know how to write Markdown. + +For all contributions you need to use Git. + +In the navigation of this docs part you can find information regarding machine-setup, programming style, used workflows, etc. diff --git a/docs/contribute/machine-setup.md b/docs/contribute/machine-setup.md new file mode 100644 index 0000000000000000000000000000000000000000..b495621a42e2f4d9a8fcaac72372830e739b13a3 --- /dev/null +++ b/docs/contribute/machine-setup.md @@ -0,0 +1,229 @@ +# Machine Setup + +## General + +### Git + +The whole project is a Git repository, +to do anything you'll need to have Git setup on your machine. + +!!! tip + We highly recommend you use Git directly typing commands to your terminal, + instead of relying on any GUI tools, IDE integration's what-so-ever. + They make life easy, sure. + But do you know, what exact calls they do under the hood? If no, don't use them. + +#### Installation + +=== "*nix" + Should be part of all major systems default software distribution path. + +=== "Windows" + !!! warning "disclaimer" + This is for people having not much experience. + If you e.g. use Cygwin, you could just install Git from there and ignore this^^ + + - Download Git: [Git-SCM][gitscm-win] + - Installation recommendations: + - opt-out from `Enable Git Credential Manager` + _We had bad experiences with it, storing wrong passwords an no one knew where to remove them as none of the pros used this thing^^_ + +#### Configuration + +After installing Git, you'll have to set a few information, +in order to be able to work with it. +Mandatory is your username and email. + +Globally set your most used username and email address you'll be using. + +```bash +git config --global user.name "" +git config --global user.email "" +``` + +!!! attention + If your global email is different from the one for this projects GitLab, + make sure to either add your main email address as committer email in your profile, + or change the git config for this project individually after cloning it. + +#### Clone project + +The toolkits root is found here: https://transfer.hft-stuttgart.de/gitlab/dtt/ +_(or click the link in the upper right corner of this docs and navigate one level up)_ + +## Java Development + +The Java parts are development with OpenJDK 8 and Maven 3.6 + +### Requirements + +- Git setup +- OpenJDK 1.8.0+ _(Java parts)_ +- Maven 3.6.0+ _(Java parts)_ + +### Installation + +#### OpenJDK + +=== "*nix" + Check your specific systems package names. + + __Ubuntu 20.04__: + ```bash + sudo apt install openjdk-11-jdk + ``` + +=== "Windows" + + - download OpenJDK: [jdk.java.net][java-net] + - extract archive to permanent place + - create/update system environment variable `JAVA_HOME`, + to the path you extracted OpenJDK to. + - update `PATH` variable including the `bin` folder of your newly placed OpenJDK + - check with a terminal that `java --version` works + +#### Maven + +=== "*nix" + Same as before, check your specific systems package names. + + __Ubuntu:__ + ```bash + sudo apt install maven + ``` + +=== "Windows" + + - download Maven binary: [maven.apache.org][maven-dl] + - extract archive to permanent place + - create/update system environment variable `MAVEN_HOME`, + to the path you extracted Maven to. + - update `PATH` including `bin` folder of maven home + - check that `mvn --version` works + +## MkDocs (Documentation) + +This project is documented using MkDocs Material. +It means we write Markdown files, organize them in a configuration file +and MkDocs generates a static Website out of it we host and you are reading right now. + +### Requirements + +- Python 3.5+ +- pip +- Python virtual environment _(optional)_ + +### Installation + +=== "*nix" + check system specific names and commands, below are some examples collected over time: + + __Ubuntu:__ + ```bash + sudo apt install python3 python3-pip python3-venv + ``` + +=== "Windows" + - download & install Python: [python.org][python-win-dl] (use executable installer version) + +- open a terminal inside the project's root directory +- _optional:_ create & activate new virtual environment: + + === "*unix" + ```bash + python3 -m venv env + . ./env/bin/activate + ``` + + === "Windows" + === "CMD" + ```cmd + python -m venv env + env\scripts\activate.bat + ``` + === "Power Shell" + !!! attention "execution policy" + You may have to first set the correct execution policy, + before able to run the activation script. + + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + + ```powershell + python -m venv env + env\scripts\Activate.ps1 + ``` + +- install all required packages: + ``` + pip install -Ur requirements.txt + ``` + +### Usage + +To work on the documentation, the mkdocs development server has to run. +On start it tells you on which port it runs (default is `8000`). + +Open the Browser on the shown URL and edit the Markdown files. +On saving changes your Browser should automatically reload the page. + +- _optional:_ enter python virtual environment + + === "*unix" + ```bash + . ./env/bin/activate + ``` + + === "Windows" + === "CMD" + ```cmd + env\scripts\activate.bat + ``` + === "Power Shell" + !!! attention "execution policy" + You may have to first set the correct execution policy, + before able to run the activation script. + + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + + ```powershell + env\scripts\Activate.ps1 + ``` + +- start MkDocs development server: + ```bash + mkdocs serve + ``` +- work +- kill dev server by pressing `ctrl+c` +- _optional:_ exit python virtual environment: + ```bash + deactivate + ``` + +### Editor/IDE + +You don't need any special IDE, as a bare minimum a text editor would work (even vim is possible). +__But don't you dare to use this crappy Microsoft built in editor!__ + +Practically it's very supportive of course, +to use a IDE that has good markdown support in terms of code-highlighting, +table formatting, etc. +Below are collected tips for different IDE's. + +=== "VSCode" + recommended extensions: + _these are the extension id's searchable from vscode_ + + - `editorconfig.editorconfig` + - `waderyan.gitblame` + - `yzhang.markdown-all-in-one` + - `jebbs.plantuml` + +[gitscm-win]: https://git-scm.com/download/win +[java-net]: https://jdk.java.net/ +[maven-dl]: https://maven.apache.org/download.cgi +[python-win-dl]: https://www.python.org/downloads/windows/ diff --git a/docs/contribute/styleguide.md b/docs/contribute/styleguide.md new file mode 100644 index 0000000000000000000000000000000000000000..375ee43af177a7aee43e0b0c5a915193cd639a4c --- /dev/null +++ b/docs/contribute/styleguide.md @@ -0,0 +1,99 @@ +# Styleguide + +If not explicitly stated otherwise, +the following takes effect for all files: + +- character encoding __utf-8__ +- line endings with __lf__ +- indentation with __4 spaces__ +- final new line + +!!! info + There will be most likely a editorconfig present, + please make sure your used IDE respects this. + +!!! tip + In general, + it's a good idea to have a look into the yet existing code, + to check how certain things were done up to now. + +## Markdown + +most important bullet points: + +- leave always an empty line above and beneath of lists. + It may render fine in normal markdown viewers, + but not in the MkDocs Pages docs (like this) + + ??? example inline end + __bad:__ + ```markdown + some text + - bullet point + - another item + more normal text + ``` + __good:__ + ```markdown + some text + + - bullet point + - another item + + more normal text + ``` + +- if you insert a link, + __always__ write the link to the bottom of the file with an alias, + ordered alphabetically. + + ??? example + __bad:__ + ```markdown + Look [here](https://www.coolsite.not/with/ultra/long/url) to read more about this. + ``` + __good:__ + ```markdown + Look [here][coolsite] to read more about this. + + [coolsite]: https://www.coolsite.not/with/ultra/long/url + ``` + +- split long sentences on punctuation and connection words like `and` & `or`. + It will have the same appearance in viewers, + but be much easier to maintain on code side. + + ??? example + __bad__: + ```markdown + Some sentence that is very long, therefore it has punctuation and has absolutely no sense at all. + ``` + > Some sentence that is very long, therefore it has punctuation and has absolutely no sense at all. + + __good:__ + ```markdown + Some sentence that is very long, + therefore it has punctuation + and has absolutely no sense at all. + ``` + + > Some sentence that is very long, + > therefore it has punctuation + > and has absolutely no sense at all. + +- tables have to be formatted in code + + ??? example + __bad:__ + ```markdown + ||column 1| + |:-|:-| + |__row 1__|cell 1| + ``` + + __good:__ + ```markdown + | | column 1 | + | :-------- | :------- | + | __row 1__ | cell 1 | + ``` diff --git a/docs/contribute/workflow.md b/docs/contribute/workflow.md new file mode 100644 index 0000000000000000000000000000000000000000..bfb9a402eb214bf90f18f67ef06ecf1a3539a4ad --- /dev/null +++ b/docs/contribute/workflow.md @@ -0,0 +1,206 @@ +# 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: `-` +- push the new branch +- create a new merge request + - title starting with `wip: ` + - description containing `closes #` + - 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/ diff --git a/mkdocs.yml b/mkdocs.yml index 2f0c98bf1f8e4cc5bd5d52ec97d2e7d63f877521..c525b4c7abc32c10ada6ae7d0b1971b8fa6bad99 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -20,6 +20,10 @@ nav: - Index: 'testrunner/index.md' - Contribute: - Index: 'contribute/index.md' + - Machine Setup: 'contribute/machine-setup.md' + - Styleguide: 'contribute/styleguide.md' + - Workflow: 'contribute/workflow.md' + theme: features: - navigation.tabs