Merge pull request #120 from CryptoRodeo/cwfconf-10293

Document guidelines for repos using git submodules

docs/modules/ROOT/pages/how-tos/_nav.adoc

@@ -29,3 +29,5 @@
 *** xref:how-tos/metadata/sboms.adoc[Inspecting SBOMs]
 *** xref:how-tos/metadata/attestations.adoc[Inspecting artifact attestations]
 ** xref:how-tos/deleting.adoc[Deleting applications and components]
+** xref:how-tos/workflows/index.adoc[Guidelines for {ProductName} integrated repositories]
+*** xref:how-tos/workflows/git-submodules.adoc[Building upstream projects with git submodules]

docs/modules/ROOT/pages/how-tos/creating.adoc

@@ -117,6 +117,20 @@ spec:
   url: "https://github.com/konflux-ci/anothertestrepo"
 --
 
+=== Context and Containerfile path
+
+==== With the UI
+In the UI, ensure that the "Dockerfile" value points to the path of the Containerfile. If the Containerfile is in the root directory of the repository, you can just input "Containerfile".
+
+==== Within the CR
+In the CR, ensure that `dockerfileUrl` points to the Containerfile filename and `context` points to where this Containerfile is located.
+
+[source, Dockerfile]
+---
+dockerfileUrl: Containerfile
+context: path/to/Containerfile
+---
+
 == Finding the built images
 
 After a pipeline completes with a built artifact, you may want to test the resulting image to ensure that it works properly. The `IMAGE_URL` Tekton result (discoverable from the UI or CLI) should be set to the pullspec for the image.

docs/modules/ROOT/pages/how-tos/workflows/git-submodules.adoc

@@ -0,0 +1,107 @@
+= Building upstream projects with git submodules
+
+This document outlines some basic guidelines for synchronizing changes between an upstream and downstream repository using Git submodules.
+
+By leveraging Git submodules, it is possible to maintain a consistent and up-to-date relationship between related repositories (upstream and downstream) while having more control of how the project is built, tested and released.
+
+Additionally, {ProductName} can automate key aspects of this process, ensuring that changes from the upstream repository are efficiently and reliably propagated to the downstream repository.
+
+== Implementing this guideline
+=== Basic definitions
+
+- **Upstream repository**: a community project which you do not have push access to (or which you do not want to push CI changes into).
+
+- **Downstream repository**: a self-owned copy of the upstream repository whose build, test, release lifecycle you want to control completely.
+
+=== Create a downstream repository
+
+The downstream repository can be used to do the following:
+
+* hold the git submodule reference to the upstream repository.
+* use the contents of the git submodule in a Containerfile for further edits.
+* onboarded onto {ProductName}.
+
+==== Configuring components
+
+CAUTION: Make sure to properly set the context and Containerfile path as required for the artifact builds.
+You can keep the context value at the the repository root where the Containerfile and git submodules are located.
+
+See xref:/how-tos/creating.adoc[Creating applications and components] for more details.
+
+==== Configuring the Containerfile
+
+In the Containerfile you can specify the git submodule directories and add any necessary edits that differ from the upstream repository. Here is a basic example:
+
+[source, Dockerfile]
+----
+FROM <base-image>
+
+# Install necessary dependencies
+RUN dnf -y install <dependencies>
+
+# Set the working directory
+ENV <SUBMODULEPKG> /path/to/submodule
+WORKDIR ${<SUBMODULEPKG>}
+
+# Commands to update the submodule for the current image build
+RUN sed -i 's/<old-text>/<new-text>/g' file/in/submodule/directory
+# Commands to build binary from submodule sources
+RUN go build file/in/submodule/directory
+
+WORKDIR /app
+
+LABEL name="<name" \
+      summary="<summary>" \
+      description="<description>"
+
+ENTRYPOINT ["<entrypoint-executable>"]
+----
+
+=== Create the git submodule for the upstream repository to track it
+
+After creating the downstream repository, add a git submodule for the upstream repository:
+
+[source, bash]
+----
+git submodule add <upstream-url>
+----
+
+Check and configure the git submodule config:
+[source, gitmodules]
+----
+# .gitmodules
+[submodule "<project-name>"]
+  path = <path-in-downstream-repository>
+  url = https://github.com/<namespace>/<project>.git
+  # Please note: by default a branch is not specified
+  # in the git submodule configuration file.
+  # Please consider setting one to prevent using the wrong branch.
+  # Here is an example of a branch being set:
+  branch = <designated-repository-branch>
+----
+
+See the link:https://git-scm.com/docs/gitsubmodules[Git documentation] for more details on configuring git submodules.
+
+=== Onboard the component onto {ProductName}
+
+After creating the downstream repository you can onboard the component. See xref:/how-tos/creating.adoc[Creating applications and components] for more details.
+
+=== Using private repositories as a git submodule:
+
+When using private repositories you must give {ProductName} access to them.
+
+NOTE: Private Gitlab submodules are currently untested.
+
+== Benefits of this guideline
+
+1. **Separation of Concerns**: The downstream repository can stay focused on its specific development goals while the submodule handles its own code. This keeps your downstream repository clean and modular.
+2. **Automatic Dependency Syncing with link:https://github.com/renovatebot/renovate[Renovate]**: By automating the dependency sync process, whether its syncing the git submodule, the Containerfile, etc. your downstream repository can always use the latest code from the upstream repository(s), ensuring that your project benefits from new features, bug fixes, and security updates.
+3. **Version Control for upstream repositories**: You can lock the submodule to a specific commit or version, giving you control over when and how updates are integrated. This is especially useful if an upstream update introduces breaking changes.
+4. **{ProductName} CI**: Automated building and testing of your software artifacts help ensure that changes in the upstream repository don't break your downstream project.
+
+== Potential drawbacks
+
+1. **Complexity**: Managing submodules and automating their updates adds complexity to your workflow, such as:
+  - Debugging issues related to submodule updates
+  - Your automation configuration can be more challenging.
+  - Updates in the submodules can be opaque which can result in drift between your build process and that of the original repository.

docs/modules/ROOT/pages/how-tos/workflows/index.adoc

@@ -0,0 +1,6 @@
+= Generic guidelines for {ProductName} integrated repositories
+
+Depending on your use case, there are several guidelines you can use for repositories that are integrated with {ProductName}:
+
+* xref:/how-tos/workflows/git-submodules.adoc[Git Submodule pattern]
+