create script which clones all QED project and setup the dev environment of each project

.ci/CI/script/create_dev_env.jl

@@ -0,0 +1,79 @@
+"""
+Clones all repositories of the QED ecosystem into a folder and sets it to the Dev branch.
+It then sets up the Julia environment for each package.
+It uses the locally cloned repositories for the QED dependencies.
+"""
+
+using CI
+using ArgParse
+using Pkg
+
+"""
+    parse_commandline()::Dict{String, Any}
+
+# Return
+
+Parsed script arguments.
+"""
+function parse_commandline()::Dict{String, Any}
+    s = ArgParseSettings()
+    s.description = "Clones all dev branch versions of the complete QED ecosystem and setup the dev branch environment of each package."
+
+    @add_arg_table! s begin
+        "project-path-prefix"
+        help = "Folder where all repositories are cloned in."
+        arg_type = String
+        required = true
+    end
+
+    return parse_args(s)
+end
+
+if abspath(PROGRAM_FILE) == @__FILE__
+    args = parse_commandline()
+    qed_prefix_path = args["project-path-prefix"]
+
+    compat_changes = CI.get_compat_changes()
+    # search for all QED packages
+    pkg_tree = CI.build_qed_dependency_graph!(
+        qed_prefix_path, compat_changes
+    )
+    # order the QED packages by it dependencies to each other
+    pkg_ordering = CI.get_package_dependency_list(pkg_tree)
+
+    for pkg_level in pkg_ordering
+        for pkg in pkg_level
+            pkg_path = joinpath(qed_prefix_path, pkg)
+            @info "Setup dev environment for package $(pkg)\n$(pkg_path)"
+
+            required_deps = CI.get_filtered_dependencies(
+                r"^(QED*|QuantumElectrodynamics*)", joinpath(pkg_path, "Project.toml")
+            )
+            linear_pkg_ordering = CI.calculate_linear_dependency_ordering(
+                pkg_ordering, required_deps
+            )
+            Pkg.activate(pkg_path)
+
+            # remove all QED packages, because otherwise Julia tries to resolve the whole
+            # environment if a package is added via Pkg.develop() which can cause circular dependencies
+            CI.remove_packages(linear_pkg_ordering, false)
+
+            CI.install_qed_dev_packages(
+                linear_pkg_ordering,
+                qed_prefix_path,
+                pkg,
+                pkg_path,
+                compat_changes,
+                false,
+            )
+        end
+    end
+
+    for pkg_level in pkg_ordering
+        for pkg in pkg_level
+            pkg_path = joinpath(qed_prefix_path, pkg)
+            # reset Project.toml to dev branch version, because uninstalling QED packages change it
+            run(`git -C $(pkg_path) checkout -- Project.toml`)
+        end
+    end
+end

docs/src/dev_guide.md

@@ -38,3 +38,16 @@ The following is a description of our release process for a version `<version>`.
 Just as with merging breaking changes into `dev`, when releasing breaking changes, extra care has to be taken. When a release contains breaking changes, some of the release-version integration tests will fail. In this case, the major version should be increased (or the minor version for versions `0.x.y`). This prevents the released downstream packages from failing since they have a `compat` entry, choosing the latest working version.
 
 The dev-integration tests assure that the latest `dev`s of all packages still work together. This means that the depending package can now be released, after changing the `compat` entry of the base package in the release branch accordingly.
+
+### Setup a Local Development Environment
+
+If you want to further develop the source code of a QED project, you must first clone the repository and check out the dev branch. You must then do the same with all QED dependencies and their dependencies. After that, you can instantiate the Julia environment of the QED project you want to modify and add the local repositories with the dev branch version as development dependencies to the environment. The process is tedious and error-prone. However, there is a script that clones all QED projects for you and sets up the development environment for each project.
+
+```bash
+# clone the script as part of the QuantumElectrodynamics.jl repository
+git clone https://github.com/QEDjl-project/QuantumElectrodynamics.jl.git
+julia --project=./QuantumElectrodynamics.jl/ -e 'import Pkg; Pkg.instantiate()'
+# Create a folder where all QED projects should be cloned.
+mkdir /path/to/qed-projects
+julia --project=./QuantumElectrodynamics.jl/ ./QuantumElectrodynamics.jl/.ci/CI/script/create_dev_env.jl /path/to/qed-projects
+```