Also see my project dotfiles and templates in: https://git.beyerstedt.de/jannik/templates-project_setup
## General Workflow
- Use a version control system, e.g. Git
- Couple your documentation versioning to the source code
* Write documentation as plain text files, e.g. in Markdown syntax
* If reasonably possible, also provides model and diagram sources. But do not put large binary blobs in the repository.
### Documentation
- Use [Markdown](https://daringfireball.net/projects/markdown/syntax) or [GitHub Flavored Markdown](https://github.github.com/gfm/) for text files
- Consider using [PlantUML](https://plantuml.com) for diagrams (because it's source is text based and can be versioned)
### Files
- File and folder names (of your source code) should:
* Just contain lower case characters
* Not contain spaces
* Separate prefixes with a dash and words with an underscore, like `topic-foo_bar.txt`
* Contain none of these special characters `|/\~!?=^%&$`
- Structure your code in a reasonable way into folders
### Git
General rules:
- Use it!
- Do not commit binary blobs (or have a good reason for it)
- Never commit
- List things, that should not be committed, in the `.gitignore` file. (Use [readily available templates](https://github.com/github/gitignore) for your programing language)
- Only commit a state, which at least compiles without errors and even better is a runnable version
Commits:
- Commits should contain one single/ standalone change or (step towards a) feature
- The code state in a commit should
* at least compile without errors
* better: compile without warnings
* best: be tested to run as expected
- Commit messages should:
* The description should use imperative language in present tense, e.g. `fix bug`/ `add new form field`
* If only a certain module was changed, prefix the description with the module name, e.g. `moduleX: add some more logging`
* Use a tag to annotate special changes, like:
+ `[DOC]`: if only documentation was changed
+ `[FIX]`: for bug fixes
+ `[TIDY]`: for refactoring actions and other cleanup steps. No functionality should be changed here!
Branching Model (adapted from [git-flow](http://nvie.com/posts/a-successful-git-branching-model/)):
- First of all, take use of the branches!
- Use a master branch for the current stable version AND a `develop` branch for the current state of development
- Use branches named `feature/$your_feature_name` to develop features without interfering with the develop branch.
- Therefore: Use a branch and merge (Pull request/ Merge Request) workflow. Even if your on your own!
