Verified Commit 9db20197 authored by Lukas Wiest's avatar Lukas Wiest 🚂
Browse files

feat(contribute): add contribution docs

parent d4c6b057
Pipeline #2401 passed with stages
in 1 minute and 32 seconds
# 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.
# 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 "<username>"
git config --global user.email "<email address>"
```
!!! 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/
# 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 |
```
# 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/
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment