diff --git a/.gitignore b/.gitignore
index 19bd1d4f3..d246502a6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,12 @@
 *.log
 *.bak
 .*
+!.gitignore
+!.ide.software.version
+!.devon.software.version
+!.ide
+!.anyedit.properties
+!.ide.properties
 target/
 eclipse-target/
 generated/
diff --git a/cli/src/main/java/com/devonfw/tools/ide/io/FileAccessImpl.java b/cli/src/main/java/com/devonfw/tools/ide/io/FileAccessImpl.java
index 54c791293..057e55158 100644
--- a/cli/src/main/java/com/devonfw/tools/ide/io/FileAccessImpl.java
+++ b/cli/src/main/java/com/devonfw/tools/ide/io/FileAccessImpl.java
@@ -543,7 +543,7 @@ private void unpack(Path file, Path targetDir, Function<InputStream, ArchiveInpu
           mkdirs(entryPath.getParent());
           Files.copy(ais, entryPath);
         }
-        if (isTar) {
+        if (isTar && !this.context.getSystemInfo().isWindows()) {
           Set<PosixFilePermission> permissions = PosixFilePermissions.fromString(permissionStr);
           Files.setPosixFilePermissions(entryPath, permissions);
         }
diff --git a/cli/src/test/java/com/devonfw/tools/ide/context/AbstractIdeContextTest.java b/cli/src/test/java/com/devonfw/tools/ide/context/AbstractIdeContextTest.java
index 966e16374..2de274fc2 100644
--- a/cli/src/test/java/com/devonfw/tools/ide/context/AbstractIdeContextTest.java
+++ b/cli/src/test/java/com/devonfw/tools/ide/context/AbstractIdeContextTest.java
@@ -32,48 +32,48 @@ public abstract class AbstractIdeContextTest extends Assertions {
   private static final int CHUNK_SIZE = 1024;
 
   /**
-   * @param projectName the (folder)name of the test project in {@link #PATH_PROJECTS}. E.g. "basic".
+   * @param projectTestCaseName the (folder)name of the project test case, in this folder a 'project' folder represents
+   *        the test project in {@link #PATH_PROJECTS}. E.g. "basic".
    * @return the {@link IdeTestContext} pointing to that project.
    */
-  protected IdeTestContext newContext(String projectName) {
+  protected IdeTestContext newContext(String projectTestCaseName) {
 
-    return newContext(projectName, null, true);
+    return newContext(projectTestCaseName, null, true);
   }
 
   /**
-   * @param projectName the (folder)name of the test project in {@link #PATH_PROJECTS}. E.g. "basic".
+   * @param projectTestCaseName the (folder)name of the project test case, in this folder a 'project' folder represents
+   *        the test project in {@link #PATH_PROJECTS}. E.g. "basic".
    * @param projectPath the relative path inside the test project where to create the context.
    * @return the {@link IdeTestContext} pointing to that project.
    */
-  protected static IdeTestContext newContext(String projectName, String projectPath) {
+  protected static IdeTestContext newContext(String projectTestCaseName, String projectPath) {
 
-    return newContext(projectName, projectPath, true);
+    return newContext(projectTestCaseName, projectPath, true);
   }
 
   /**
-   * @param projectName the (folder)name of the test project in {@link #PATH_PROJECTS}. E.g. "basic".
+   * @param projectTestCaseName the (folder)name of the project test case, in this folder a 'project' folder represents
+   *        the test project in {@link #PATH_PROJECTS}. E.g. "basic".
    * @param projectPath the relative path inside the test project where to create the context.
    * @param copyForMutation - {@code true} to create a copy of the project that can be modified by the test,
    *        {@code false} otherwise (only to save resources if you are 100% sure that your test never modifies anything
-   *        in that project.
+   *        in that project.)
    * @param answers the answers to use for the {@link IdeTestContext}.
    * @return the {@link IdeTestContext} pointing to that project.
    */
-  protected static IdeTestContext newContext(String projectName, String projectPath, boolean copyForMutation,
-      String... answers) {
+  protected static IdeTestContext newContext(String projectTestCaseName, String projectPath, boolean copyForMutation) {
 
-    Path sourceDir = PATH_PROJECTS.resolve(projectName);
-    Path userDir = sourceDir;
+    Path sourceDir = PATH_PROJECTS.resolve(projectTestCaseName);
+    Path userDir = sourceDir.resolve("project");
     IdeTestContext context;
     if (copyForMutation) {
-      Path projectDir = PATH_PROJECTS_COPY.resolve(projectName);
+      Path projectDir = PATH_PROJECTS_COPY.resolve(projectTestCaseName);
       FileAccess fileAccess = new FileAccessImpl(IdeTestContextMock.get());
       fileAccess.delete(projectDir);
       fileAccess.mkdirs(PATH_PROJECTS_COPY);
       fileAccess.copy(sourceDir, projectDir, FileCopyMode.COPY_TREE_OVERRIDE_TREE);
-      fileAccess.copy(PATH_PROJECTS.resolve(IdeContext.FOLDER_IDE), PATH_PROJECTS_COPY.resolve(IdeContext.FOLDER_IDE),
-          FileCopyMode.COPY_TREE_OVERRIDE_TREE);
-      userDir = projectDir;
+      userDir = projectDir.resolve("project");
     }
     if (projectPath != null) {
       userDir = userDir.resolve(projectPath);
diff --git a/cli/src/test/java/com/devonfw/tools/ide/merge/DirectoryMergerTest.java b/cli/src/test/java/com/devonfw/tools/ide/merge/DirectoryMergerTest.java
index 4f3bb2342..ce995dd8f 100644
--- a/cli/src/test/java/com/devonfw/tools/ide/merge/DirectoryMergerTest.java
+++ b/cli/src/test/java/com/devonfw/tools/ide/merge/DirectoryMergerTest.java
@@ -17,8 +17,8 @@
  */
 public class DirectoryMergerTest extends AbstractIdeContextTest {
 
-  private static final String IDE_HOME = PATH_PROJECTS.resolve(PROJECT_BASIC).toAbsolutePath().toString().replace('\\',
-      '/');
+  private static final String IDE_HOME = PATH_PROJECTS.resolve(PROJECT_BASIC).resolve("project").toAbsolutePath()
+      .toString().replace('\\', '/');
 
   private static final Prop JAVA_VERSION = new Prop("java.version", "1.11");
 
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/mvn/secondMvnEdition/.gitkeep b/cli/src/test/resources/ide-projects/_ide/urls/mvn/secondMvnEdition/.gitkeep
deleted file mode 100644
index e69de29bb..000000000
diff --git a/cli/src/test/resources/ide-projects/_ide/software/default/az/az/testVersion/.ide.software.version b/cli/src/test/resources/ide-projects/basic/_ide/software/default/az/az/testVersion/.ide.software.version
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/software/default/az/az/testVersion/.ide.software.version
rename to cli/src/test/resources/ide-projects/basic/_ide/software/default/az/az/testVersion/.ide.software.version
diff --git a/cli/src/test/resources/ide-projects/_ide/software/readme b/cli/src/test/resources/ide-projects/basic/_ide/software/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/software/readme
rename to cli/src/test/resources/ide-projects/basic/_ide/software/readme
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/linux_x64.sha256 b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/linux_x64.sha256
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/linux_x64.sha256
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/linux_x64.sha256
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/linux_x64.urls b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/linux_x64.urls
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/linux_x64.urls
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/linux_x64.urls
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/mac_x64.sha256 b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/mac_x64.sha256
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/mac_x64.sha256
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/mac_x64.sha256
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/mac_x64.urls b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/mac_x64.urls
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/mac_x64.urls
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/mac_x64.urls
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/status.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/status.json
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/status.json
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/status.json
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/windows_x64.urls b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/windows_x64.urls
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/windows_x64.urls
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/windows_x64.urls
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/windows_x64.urls.sha256 b/cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/windows_x64.urls.sha256
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/java/java/17.0.6/windows_x64.urls.sha256
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/java/java/17.0.6/windows_x64.urls.sha256
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/linux_x64.sha256 b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/linux_x64.sha256
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/linux_x64.sha256
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/linux_x64.sha256
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/linux_x64.urls b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/linux_x64.urls
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/linux_x64.urls
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/linux_x64.urls
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/mac_x64.sha256 b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/mac_x64.sha256
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/mac_x64.sha256
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/mac_x64.sha256
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/mac_x64.urls b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/mac_x64.urls
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/mac_x64.urls
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/mac_x64.urls
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/status.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/status.json
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/status.json
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/status.json
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls.sha256 b/cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls.sha256
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls.sha256
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/jmc/jmc/8.3.0/windows_x64.urls.sha256
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/3.0.5/status.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/3.0.5/status.json
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/3.0.5/status.json
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/3.0.5/status.json
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/3.1.0/status.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/3.1.0/status.json
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/3.1.0/status.json
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/3.1.0/status.json
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/3.2.1/status.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/3.2.1/status.json
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/3.2.1/status.json
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/3.2.1/status.json
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/security.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/security.json
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/mvn/mvn/security.json
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/mvn/security.json
diff --git a/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/secondMvnEdition/3.2.1/status.json b/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/secondMvnEdition/3.2.1/status.json
new file mode 100644
index 000000000..e66f9ed76
--- /dev/null
+++ b/cli/src/test/resources/ide-projects/basic/_ide/urls/mvn/secondMvnEdition/3.2.1/status.json
@@ -0,0 +1,10 @@
+
+  "manual" : false,
+  "urls" : {
+    "-997329125" : {
+      "success" : {
+        "timestamp" : "2023-04-28T07:12:26.601818Z"
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/cli/src/test/resources/ide-projects/_ide/urls/readme b/cli/src/test/resources/ide-projects/basic/_ide/urls/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/_ide/urls/readme
rename to cli/src/test/resources/ide-projects/basic/_ide/urls/readme
diff --git a/cli/src/test/resources/ide-projects/basic/conf/ide.properties b/cli/src/test/resources/ide-projects/basic/project/conf/ide.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/conf/ide.properties
rename to cli/src/test/resources/ide-projects/basic/project/conf/ide.properties
diff --git a/cli/src/test/resources/ide-projects/basic/home/.ide/ide.properties b/cli/src/test/resources/ide-projects/basic/project/home/.ide/ide.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/home/.ide/ide.properties
rename to cli/src/test/resources/ide-projects/basic/project/home/.ide/ide.properties
diff --git a/cli/src/test/resources/ide-projects/basic/home/.ide/settings/eclipse/plugins/anyedit.properties b/cli/src/test/resources/ide-projects/basic/project/home/.ide/settings/eclipse/plugins/anyedit.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/home/.ide/settings/eclipse/plugins/anyedit.properties
rename to cli/src/test/resources/ide-projects/basic/project/home/.ide/settings/eclipse/plugins/anyedit.properties
diff --git a/cli/src/test/resources/ide-projects/basic/home/Downloads/ide/readme b/cli/src/test/resources/ide-projects/basic/project/home/Downloads/ide/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/home/Downloads/ide/readme
rename to cli/src/test/resources/ide-projects/basic/project/home/Downloads/ide/readme
diff --git a/cli/src/test/resources/ide-projects/basic/home/readme b/cli/src/test/resources/ide-projects/basic/project/home/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/home/readme
rename to cli/src/test/resources/ide-projects/basic/project/home/readme
diff --git a/cli/src/test/resources/ide-projects/basic/project/readme b/cli/src/test/resources/ide-projects/basic/project/readme
new file mode 100644
index 000000000..256f5732c
--- /dev/null
+++ b/cli/src/test/resources/ide-projects/basic/project/readme
@@ -0,0 +1 @@
+this is the IDE_HOME directory
\ No newline at end of file
diff --git a/cli/src/test/resources/ide-projects/basic/scripts/ide b/cli/src/test/resources/ide-projects/basic/project/scripts/ide
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/scripts/ide
rename to cli/src/test/resources/ide-projects/basic/project/scripts/ide
diff --git a/cli/src/test/resources/ide-projects/basic/settings/eclipse/plugins/anyedit.properties b/cli/src/test/resources/ide-projects/basic/project/settings/eclipse/plugins/anyedit.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/settings/eclipse/plugins/anyedit.properties
rename to cli/src/test/resources/ide-projects/basic/project/settings/eclipse/plugins/anyedit.properties
diff --git a/cli/src/test/resources/ide-projects/basic/settings/eclipse/plugins/checkstyle.properties b/cli/src/test/resources/ide-projects/basic/project/settings/eclipse/plugins/checkstyle.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/settings/eclipse/plugins/checkstyle.properties
rename to cli/src/test/resources/ide-projects/basic/project/settings/eclipse/plugins/checkstyle.properties
diff --git a/cli/src/test/resources/ide-projects/basic/settings/ide.properties b/cli/src/test/resources/ide-projects/basic/project/settings/ide.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/settings/ide.properties
rename to cli/src/test/resources/ide-projects/basic/project/settings/ide.properties
diff --git a/cli/src/test/resources/ide-projects/basic/setup b/cli/src/test/resources/ide-projects/basic/project/setup
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/setup
rename to cli/src/test/resources/ide-projects/basic/project/setup
diff --git a/cli/src/test/resources/ide-projects/basic/software/java/bin/readme b/cli/src/test/resources/ide-projects/basic/project/software/java/bin/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/software/java/bin/readme
rename to cli/src/test/resources/ide-projects/basic/project/software/java/bin/readme
diff --git a/cli/src/test/resources/ide-projects/basic/software/mvn/.devon.software.version b/cli/src/test/resources/ide-projects/basic/project/software/mvn/.devon.software.version
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/software/mvn/.devon.software.version
rename to cli/src/test/resources/ide-projects/basic/project/software/mvn/.devon.software.version
diff --git a/cli/src/test/resources/ide-projects/basic/software/mvn/bin/readme b/cli/src/test/resources/ide-projects/basic/project/software/mvn/bin/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/software/mvn/bin/readme
rename to cli/src/test/resources/ide-projects/basic/project/software/mvn/bin/readme
diff --git a/cli/src/test/resources/ide-projects/basic/workspaces/foo-test/ide.properties b/cli/src/test/resources/ide-projects/basic/project/workspaces/foo-test/ide.properties
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/workspaces/foo-test/ide.properties
rename to cli/src/test/resources/ide-projects/basic/project/workspaces/foo-test/ide.properties
diff --git a/cli/src/test/resources/ide-projects/basic/workspaces/foo-test/my-git-repo/readme b/cli/src/test/resources/ide-projects/basic/project/workspaces/foo-test/my-git-repo/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/workspaces/foo-test/my-git-repo/readme
rename to cli/src/test/resources/ide-projects/basic/project/workspaces/foo-test/my-git-repo/readme
diff --git a/cli/src/test/resources/ide-projects/basic/workspaces/foo-test/readme b/cli/src/test/resources/ide-projects/basic/project/workspaces/foo-test/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/workspaces/foo-test/readme
rename to cli/src/test/resources/ide-projects/basic/project/workspaces/foo-test/readme
diff --git a/cli/src/test/resources/ide-projects/basic/workspaces/main/readme b/cli/src/test/resources/ide-projects/basic/project/workspaces/main/readme
similarity index 100%
rename from cli/src/test/resources/ide-projects/basic/workspaces/main/readme
rename to cli/src/test/resources/ide-projects/basic/project/workspaces/main/readme
diff --git a/cli/src/test/resources/ide-projects/basic/readme b/cli/src/test/resources/ide-projects/basic/readme
index 256f5732c..15b91829e 100644
--- a/cli/src/test/resources/ide-projects/basic/readme
+++ b/cli/src/test/resources/ide-projects/basic/readme
@@ -1 +1 @@
-this is the IDE_HOME directory
\ No newline at end of file
+this is the IDE_ROOT directory
\ No newline at end of file
diff --git a/cli/src/test/resources/ide-projects/readme b/cli/src/test/resources/ide-projects/readme
deleted file mode 100644
index 15b91829e..000000000
--- a/cli/src/test/resources/ide-projects/readme
+++ /dev/null
@@ -1 +0,0 @@
-this is the IDE_ROOT directory
\ No newline at end of file
diff --git a/documentation/coding-conventions.asciidoc b/documentation/coding-conventions.asciidoc
index c56156fdf..b47bfeaf9 100644
--- a/documentation/coding-conventions.asciidoc
+++ b/documentation/coding-conventions.asciidoc
@@ -125,7 +125,7 @@ So instead of just saying "Something failed" a really good example could look li
 LOG.error("An unexpected error occurred whilst downloading the tool {} with edition {} and version {} from URL {}.", tool, edition, version, url, e);
 ----
 
-=== Prefer general API
+== Prefer general API
 Avoid unnecessary strong bindings:
 
 * Do not bind your code to implementations such as `Vector` or `ArrayList` instead of `List`
@@ -133,7 +133,7 @@ Avoid unnecessary strong bindings:
 ** prefer `Collection` over `List` or `Set` where the difference does not matter (e.g. only use `Set` when you require uniqueness or highly efficient `contains`)
 ** consider preferring `Collection<? extends Foo>` over `Collection<Foo>` when `Foo` is an interface or super-class
 
-=== Prefer primitive types
+== Prefer primitive types
 In general prefer primitive types (`boolean`, `int`, `long`, ...) instead of corresponding boxed object types (`Boolean`, `Integer`, `Long`, ...).
 Only use boxed object types, if you explicitly want to allow `null` as a value.
 Typically you never want to use `Boolean` but instead use `boolean`.
@@ -208,6 +208,47 @@ So we conclude:
 * In classes we declare the constant with the visibility followed by the keywords `static final`.
 * In interfaces, we omit all modifiers as they always default to `public static final` for type variables.
 
+== Refactorings
+
+Do refactorings with care and follow these best-practices:
+
+* use `git mv «old» «new»` to move or rename things in git. Otherwise your diff may show that a file has been deleted somewhere and another file has been added but you cannot see that this file was moved/renamed and what changed inside the file.
+* do not change Java signatures like in a text editor but use refactoring capabilities of your IDE. So e.g. when changing a method name, adding or removing a parameter, always use refactoring as otherwise you easily break references (and JavaDoc references will not give you compile errors so you break things without noticing).
+* when adding paramaters to methods, please always consider to keep the existing signature and just create a new variant of the method with an additional parameter.
+
+Lets assume we have this method:
+[source,java]
+----
+public void doSomething() {
+  // ...
+}
+----
+
+Now, assuming this method is called from multiple places, this change is bad:
+[source,java]
+----
+// bad
+public void doSomething(boolean newFlag) {
+  // ...
+}
+----
+The reason is that it is most likely causing a lot of merge conflicts for feature-branches and PRs of other developers, currently working with code calling `doSomething()` that will not work after the change.
+
+Instead keep the existing signature and add a new one:
+[source,java]
+----
+// good
+public void doSomething() {
+  doSomething(false);
+}
+public void doSomething(boolean newFlag) {
+  // ...
+}
+----
+
+Typically, you should design flags such that `false` is a reasonable default.
+That is why we are passing `false` in the example from the existing method to the new one.
+
 == Optionals
 With `Optional` you can wrap values to avoid a `NullPointerException` (NPE).
 However, it is not a good code-style to use `Optional` for every parameter or result to express that it may be null.