Merge branch 'git-workflow' into 'main'

Git workflow

See merge request farchm01/open_source_dev!1

README.md

@@ -32,31 +32,56 @@ Project Setup <a name="project_setup"></a>
 
 ### Version Control <a name="version_control"></a>
 
-Different Websites to host a `git` repository:
+Different Websites to host a Git repository:
   - **PTB-GitLab:** <a href="https://gitlab1.ptb.de/" target="_blank">https://gitlab1.ptb.de/</a>
   - GitLab: <a href="https://gitlab.com" target="_blank">https://gitlab.com</a>
   - Github (Google): <a href="https://github.com" target="_blank">https://github.com</a>
   - Bitbucket (Atlassian): <a href="https://bitbucket.org" target="_blank">https://bitbucket.org</a>
 
-Especially if a project is developed/maintained by more then one person, it is useful to determine a develepment strategy (branching model) to keep the history clean and readible.
+###### Git Workflow
+
+If a project is developed/maintained by more then one person, it is useful to determine a develepment strategy (branching model) to keep the history clean and readible.
+
+**Groups:**
 If the project is not tied to a single person, or if multiple people are responsible to maintain the project, it might be useful to create a <a href="https://docs.gitlab.com/ee/user/group/" target="_blank">GitLab Group</a>.
 This way the project itself is not tied to a specific user account and additional projects may be linked under the same group as well.
 (See the <a href="https://gitlab1.ptb.de/pythia/" target="_blank">PyThia Group</a> as an example.)
 
+In particular, it might be useful to create a Git group for your working group.
+This way you can easily grant access to every Git repository in your workgroup to everyone of your workgroup.
+You can even define different roles, to e.g. prevent specific members (e.g. students) to push to certain branches (e.g. main branch of your PhD repository).
+
+**Branching models:**
+A Git workflow or branching model is essentially fixing a way to create new branches and enforce certain criteria for different branches.
+This way everyone working with the code, either through usage or contribution, knows how to obtain a stable version of the software, checkout the latest development stages or add features in a reproducable way.
+There exist a multitude of common branching models, neither of them being better then the other.
+For examples, see either the <a href="https://docs.github.com/en/get-started/quickstart/github-flow" target="_blank">GitHub flow</a> model or the <a href="https://gitlab1.ptb.de/pythia/pythia/-/blob/development/DEVELOPERS.md#git-workflow" target="_blank">branching model of PyThia</a>.
+A good overview of different Git workflows can also be found <a href="https://medium.com/javarevisited/5-different-git-workflows-50f75d8783a7" target="_blank">on this website</a>.
+
+Here are some examples:
+  1. If only you are working on your repository and if you ever only add new things, you can use only one branch (main) to build your code.
+  2. If you want to always have working version of your code, you can work linearly on a `development` branch and merge that into the `main` branch only if everything works.
+  3. If you work on different features simultaneously or want to test things out, you can create `feature-branches`, code on them and merge them into the `development` branch once everything works in them.
+
+**Tips:**
+  1. You can "squash" commit messages of feature branches, if you are not interested in keeping every "Bugfix" commit message in your history.
+  2. When working with (a lot of) different branches, make sure you can easily see which branch you are on.
+     For example your can change the layout of your bash command line to show the current branch:
+     ![Git branch in terminal](./img/branch_in_terminal.png)
+
+###### Git Commit Messages
+
 To keep the Git history clean and understandable, it is best practice to follow a consistent commit style guide, as e.g. the one discussed in <a href="http://who-t.blogspot.com/2009/12/on-commit-messages.html" target="_blank">this blog post</a>.
-As an overview on the common git commit message style, <a href="https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html" target="_blank">this cheat sheet</a> might help a lot.
+As an overview on the common Git commit message style, <a href="https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html" target="_blank">this cheat sheet</a> might help a lot.
 
 **General rules:**
   - Each commit message consists of a **header**, a **body** and a **footer**.
   - The **header** is mandatory and should not exceed 50 characters.
   - The **body** and **footer** are optional, however mentioning an issue in the footer will close the issue automatically.
   - Any line of the commit message cannot be longer than 72 characters!
-    This allows the message to be easier to read on GitLab as well as in various git tools.
+    This allows the message to be easier to read on GitLab as well as in various Git tools.
 
-Another important thing when developing code with multiple developers, maintainers and/or users is to choose (and specify) a branching model.
-This way everyone working with the code, either through usage or contribution, knows how to obtain a stable version of the software, checkout the latest development stages or add features in a reproducable way.
-There exist a multitude of branching models, neither of them being better then the other.
-For examples, see either the <a href="https://docs.github.com/en/get-started/quickstart/github-flow" target="_blank">GitHub flow</a> model or the <a href="https://gitlab1.ptb.de/pythia/pythia/-/blob/development/DEVELOPERS.md#git-workflow" target="_blank">branching model of PyThia</a>.
+###### Use the .gitignore
 
 To keep only the relevant information in your repository, you should specify which files should not be tracked by `Git`.
 To do so, simply add a `.gitignore` file to your repository root.
@@ -77,7 +102,7 @@ app/config/config.ini
 
 **Important:**
 Do not use `jupyter notebooks` when implementing code used for version control, as `Git` is only able to use diffs efficiently for plain text files.
-Similarily, don't add data files (`.npz`, `.hdf5`, etc.), documents (`.pdf`, `.docx`, etc.) or images (`.png`, `.jpeg`, `.svg`, etc.) to your git repository.
+Similarily, don't add data files (`.npz`, `.hdf5`, etc.), documents (`.pdf`, `.docx`, etc.) or images (`.png`, `.jpeg`, `.svg`, etc.) to your Git repository.
 
 ### README and other Information <a name="readme"></a>
 
@@ -97,7 +122,7 @@ Finally, if other people's work is based on your code, you should include a `CHA
 
 Choose a way to determine different versions of your code, such as <a href="https://semver.org/" target="_blank">semantic versioning</a>.
 This way users of your code know which version of your code they are working with, which helps with reproducability of complex code projects later on.
-Best practice is to use e.g. <a href="https://docs.gitlab.com/ee/topics/git/tags.html" target="_blank">GitLab Tags</a> to distinguish different versions of the code in the git history.
+Best practice is to use e.g. <a href="https://docs.gitlab.com/ee/topics/git/tags.html" target="_blank">GitLab Tags</a> to distinguish different versions of the code in the Git history.
 With this, it is very easy to checkout a certain commit to install a specific version.
 
 Coding (Python) <a name="coding_python"></a>
@@ -179,10 +204,10 @@ You can install mamba by running `conda install mamba -n base -c conda-forge` in
 ###### 2. Writing scientific code with own package:
 Assume you have a repository with some utility functions and another one in which you implement some application.
 You can (locally) import the utility package, but communicating this to others is difficult.
-Moreover, if you need to change something in the utility repository while working on an application, you need to manage multiple git repositories.
+Moreover, if you need to change something in the utility repository while working on an application, you need to manage multiple Git repositories.
 For this case, you can use <a href="https://git-scm.com/book/en/v2/Git-Tools-Submodules" target="_blank">Git Submodules</a> to integrate a snapshot of the utility repository into you application one.
 Simply navigate to the submodule (sub-directory) and start editing/commiting your files there.
-It is basically your git-repo inside another git repo.
+It is basically your Git-repo inside another Git repo.
 
 **Tip:**
 You should still use an environment file to track package versions of other packages.
@@ -334,7 +359,7 @@ You can create an account there and simply link to your repository.
 Read the Docs will even create different versions of the documentation based on the commits of your Git repository, i.e., a "stable" and a "latest" version you can specify the branches of as well as versions for different tags (v1.2.17, v2.0.1) of your project.
 This way, even if somebody uses an older version of your code, they still can access the correct documentation.
 
-All you need to do from the git side is include a `.readthedocs.yml` file in your repository root that looks something like this:
+All you need to do from the Git side is include a `.readthedocs.yml` file in your repository root that looks something like this:
 ```yaml
 # Required
 version: 2