docs(readme): explain handling of git submodules (DEV-1502) (#256)

.github/pull_request_template.md

@@ -1,9 +1,12 @@
 ===REMOVE===
 
-Important! Please follow the new guidelines for naming Pull
-Requests: https://docs.dasch.swiss/latest/developers/dsp/contribution/#pull-request-guidelines
+Important! Please follow the guidelines for naming Pull Requests: 
+https://docs.dasch.swiss/latest/developers/dsp/contribution/#pull-request-guidelines
 
-> **Note:** If a pull request consists consists of *only one* commit when squash-merging it to main, the commit message will *not* be correct. In this case you have to manually ensure that the commit message is identical to the PR title, not the commit that the PR consists of.
+**Note:** When squash-merging a PR into the main branch, the PR title will be taken as squash-merge commit message that 
+appears in the main branch. But this automatism only works for PRs that consist of more than one commit. If a PR consists 
+of *only one* commit, GitHub will take the name of the commit as squash-merge-commit message. In this case, you have to
+manually ensure that the squash-merge commit message is identical to the PR title.
 
 ===REMOVE===
 

.github/workflows/check-pr-title.yml

@@ -12,7 +12,7 @@ jobs:
       # check PR title
       - uses: deepakputhraya/action-pr-title@master
         with:
-          regex: '([a-z])+(\(([0-9a-z\-_, ])+\))?!?: [a-z]([a-zA-Z-\.\d \(\)\[\]#_,])+$' # Regex the title should match.
+          regex: '([a-z])+(\(([0-9a-z\-_, ])+\))?!?: [a-z].+\(DEV-\d+\)$' # Regex the title should match.
           allowed_prefixes: "fix,refactor,feat,docs,chore,style,test" # title should start with the given prefix
           disallowed_prefixes: "feature,hotfix" # title should not start with the given prefix
           prefix_case_sensitive: true # title prefix are case insensitive

README.md

@@ -2,16 +2,16 @@
 
 # DSP-TOOLS - DaSCH Service Platform Tools
 
-dsp-tools is a command line tool that helps you interacting with the DaSCH Service Platform API.  
-Go to [Full Documentation](https://docs.dasch.swiss/latest/DSP-TOOLS)
+dsp-tools is a command line tool that helps you to interact with the DaSCH Service Platform API. Consult the full 
+documentation [here](https://docs.dasch.swiss/latest/DSP-TOOLS).
 
 
 ## Information for developers
 
 There is a `Makefile` for all the following tasks (and more). Type `make` to print the available targets. 
 
 For a quick start, use: 
-```
+```bash
 pip install pipenv
 pipenv install --dev
 pipenv run make install
@@ -26,6 +26,84 @@ make install
 ```
 
 
+## Git submodules
+
+This repository embeds [https://github.com/dasch-swiss/0123-import-scripts](https://github.com/dasch-swiss/0123-import-scripts) 
+as a Git submodule in `knora/dsplib/import_scripts`. That means that `knora/dsplib/import_scripts` has no contents, but
+only a reference to a certain commit in the main branch of `0123-import-scripts`. When you clone `dsp-tools` from GitHub 
+as usual, `knora/dsplib/import_scripts` will be empty.
+
+
+### Passively using the contents of the submodule
+
+If you don't have a clone of dsp-tools yet, clone it with 
+
+```bash
+git clone --recurse-submodules https://github.com/dasch-swiss/dsp-tools.git
+```
+
+After cloning it that way, and after some time has passed, you might want to get the latest changes from GitHub:
+
+```bash
+cd dsp-tools
+git pull --recurse-submodules
+```
+
+These two commands take care of the submodule, so that its contents are cloned/pulled as well. 
+
+In case you have an old clone of dsp-tools, without the submodule, and you want to update it, you have to proceed 
+differently: 
+
+```bash
+cd dsp-tools
+git pull
+git submodule update --init --recursive
+```
+
+Some notes:
+ - `git clone --recurse-submodules <repo>` is shorthand for `git clone <repo>; cd <repo>; git submodule update --init --recursive`
+ - `git pull --recurse-submodules` is shorthand for `git pull; git submodule update --init --recursive`
+ - `--init` is necessary if you don't have the submodule `knora/dsplib/import_scripts` yet. In all successive calls, 
+   when the submodule is already on your machine, the flag `--init` can be omitted.
+ - `--recursive` is optional, in case there would be more than one (nested) submodules inside dsp-tools. 
+ - Since Git 2.15, you can tell Git to use `--recurse-submodules` for all commands that support it (except `clone`), 
+   with `git config submodule.recurse true`.
+ - These explanations rely on [the official Git Submodules documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+
+
+### Actively working with the contents of the submodule
+
+After retrieving the contents of a submodule as described in the paragraph above, it is in "detached HEAD" state. Before 
+committing to it, the `main` branch needs to be checked out. The order how to proceed is the following:
+
+```bash
+cd knora/dsplib/import_scripts
+git checkout main                     # check out main branch of 0123-import-scripts
+# (modify contents of submodule)
+git add .
+git commit -m "modify submodule"
+git push origin main                  # push to origin of 0123-import-scripts
+cd ../../..
+git add knora/dsplib/import_scripts
+git commit -m "modify submodule"
+git push origin feature-branch        # push to origin of dsp-tools
+```
+
+When switching between branches, there are two options:
+
+1. By default (`submodule.recurse` is false AND branches are switched with `git checkout <branch>`), the contents of 
+  submodules will not be updated.
+2. If `submodule.recurse` has been set to true, OR if branches are switched with `git checkout <branch> 
+    --recurse-submodules`, the contents of submodules will be updated according to the commit recorded in the 
+   superproject. If local modifications in a submodule would be overwritten, the checkout will fail.
+
+To quickly switch between branches when you have 
+uncommitted work in the submodule, the first option might be preferable. After merging a Pull Request and switching 
+back to the main branch, the second option might be more suitable.  
+Read more about the checkout options in [the official documentation](https://git-scm.com/docs/git-checkout#Documentation/git-checkout.txt---recurse-submodules)
+
+
+
 ## Pipenv
 
 We use pipenv for our dependency management. There are two ways to get started: