systemd/README: improve readme

1 files changed, 28 insertions, 22 deletions

diff --git a/src/libnm-systemd-shared/README.md b/src/libnm-systemd-shared/README.md
index 5011b2367d..6609df6c84 100644
--- a/src/libnm-systemd-shared/README.md
+++ b/src/libnm-systemd-shared/README.md
@@ -1,27 +1,29 @@
 libnm-systemd-shared
 ====================
 
-This is a fork of systemd source files that are compiled
-as a static library with general purpose helpers.
+This is a fork of systemd source files that are compiled as a static library
+with general purpose helpers.
 
-We mainly need this for [../libnm-systemd-core/](../libnm-systemd-core/),
-which contains systemd library with network tools (like DHCPv6).
+We mainly need this for [../libnm-systemd-core/](../libnm-systemd-core/), which
+contains builds network tools that we use (our internal DHCPv6 library).
 
-We should not use systemd directly from our sources, beyond what
-we really need to make get libnm-systemd-core working.
+We should not use systemd directly from our sources, beyond what we really need
+to make get libnm-systemd-core working. That means, although the systemd code
+contains many useful utility functions, we should not use them beyond what we
+really need, because one day we want to drop this code again.
 
 
 Reimport Upstream Code
 ----------------------
 
-We want to avoid deviations in our fork, and frequently re-import
-latest systemd version (every 4 to 8 weeks). The reason is that we
-frequently should check whether important fixes were done in upstream
-systemd, and the effort of doing that is half the work of just reimporting.
-Also, by reimporting frequently, we avoid deviating hugely (instead we only deviate
-largely).
+We want to avoid deviations in our fork, and frequently re-import latest
+systemd version (every 4 to 8 weeks). The reason is that we frequently should
+check whether important fixes were done in upstream systemd, and the effort of
+doing that check is half the work of a full reimport.  Also, by reimporting
+frequently, we avoid deviating hugely and fall back too much.
 
-Of course this is cumbersome. We should replace systemd code with something else.
+Of course this is cumbersome. We therefore should avoid using the systemd code
+as much as we can, and work towards dropping it altogether.
 
 To do a re-import, do:
 
@@ -36,16 +38,20 @@ To do a re-import, do:
 - checkout `main` branch, and `git merge systemd`. Fix all issues, test,
   repeat.
 
-- open merge request, check that all tests pass. In particular, enable build
-  on all test distributions.
+- open merge request, check that all tests pass. In particular, enable build on
+  all test distributions in gitlab-ci.
 
-- push `main` and `systemd` branch.
+- push `main` and `systemd` branches. Compare how it was done during past imports.
 
 ### Hints
 
-- Eagerly commented out the unused function.
-- Patching header is best avoided, #if 0  and #endif  function patching should
-  only be used in the C source.
-- We may create some dummy files in
-  `src/libnm-systemd-{shared,core}/sd-adapt-\*/` for resolving the compiling
-  error (missing header file)
+- Eagerly commented out unused functions definitions with `#if 0` and `#endif`.
+- Patching header files is best avoided and keep function declarations.
+- We may create some dummy header files in `src/libnm-systemd-{shared,core}/sd-adapt-\*/`
+  if that is a suitable way to get the code to compile, while having minimal modifications
+  to systemd code.
+- Let git be aware of the merge history. Git can help you to better resolve merge conflicts.
+  For example, a plain rebase of the branch on `main` will result in conflicts. Instead,
+  create a temporary branch and merge the code (no rebase). With the help of the history,
+  git will not run into conflicts during merging. Then, the merged git-tree contains the
+  desired content of the files.