From 1dc84836adf68aaf1741dd50da05fb05b1230a06 Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com> Date: Thu, 17 Nov 2022 12:20:44 +0100 Subject: [PATCH] docs(readme): explain handling of git submodules (DEV-1502) (#256) --- .github/pull_request_template.md | 9 ++- .github/workflows/check-pr-title.yml | 2 +- README.md | 84 +++++++++++++++++++++++++++- 3 files changed, 88 insertions(+), 7 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b8d587daf..0c27ae626 100644 --- a/.github/pull_request_template.md +++ b/.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=== diff --git a/.github/workflows/check-pr-title.yml b/.github/workflows/check-pr-title.yml index 04673048a..e2d674c43 100644 --- a/.github/workflows/check-pr-title.yml +++ b/.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 diff --git a/README.md b/README.md index c805dc805..9c999f1ff 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ # 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 @@ -11,7 +11,7 @@ Go to [Full Documentation](https://docs.dasch.swiss/latest/DSP-TOOLS) 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 ` is shorthand for `git clone ; cd ; 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 `), 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 + --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: