From 4d05b24369eec3eb5d5a04fac7d79094c153e986 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 29 Aug 2025 12:52:11 +0000
Subject: [PATCH] feat(docs): add guide for merging base repo

This commit introduces a new guide on how to merge the `base` repository into an existing project. The guide covers all the necessary steps, from adding `base` as a remote to handling merge conflicts and creating a pull request.

The new file `docs/merging-base.md` contains the comprehensive guide.

The main documentation file `docs/README.md` has been updated to include a link to this new guide, ensuring it is discoverable for users.
---
 docs/README.md       |  1 +
 docs/merging-base.md | 91 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 docs/merging-base.md

diff --git a/docs/README.md b/docs/README.md
index 3ef270a..aa01d8d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,5 +9,6 @@ This directory contains the documentation for the `base` project.
 - **[GitHub Workflows](./github-workflows.md)**: An explanation of the CI/CD workflows for linting, testing, and releasing.
 - **[Licensing Information](./licensing.md)**: Details on the MIT License and how to properly attribute copyright.
 - **[Deploying to Render.com](./render.md)**: Instructions for deploying the project to the Render.com platform.
+- **[Merging `base` Into an Existing Repository](./merging-base.md)**: A guide on how to incorporate `base` into an existing project.
 - **[Standard Repository Files](./standard-files.md)**: An explanation of the standard configuration files like `.gitignore`, `.editorconfig`, and `.gitattributes`.
 - **[Maintaining `base` as a Template Repository](./template-repo.md)**: A guide for maintainers of this template, outlining best practices and administrative steps.
diff --git a/docs/merging-base.md b/docs/merging-base.md
new file mode 100644
index 0000000..eb086ab
--- /dev/null
+++ b/docs/merging-base.md
@@ -0,0 +1,91 @@
+# Merging `base` Into an Existing Repository
+
+This guide explains how to merge the `base` repository into your existing project. This is useful for incorporating the `base` features, such as the Docker environment and GitHub Actions, into a project that has already been started.
+
+## 1. Add `base` as a Remote
+
+First, you need to add the `base` repository as a remote to your local Git repository. This allows you to fetch its branches and history.
+
+Open your terminal, navigate to your project's root directory, and run the following command:
+
+```bash
+git remote add base https://github.com/attogram/base.git
+```
+
+This command adds a new remote named `base` that points to the official `base` repository.
+
+## 2. Fetch and Merge `base`
+
+Next, fetch the `base` repository's history and merge its `main` branch into your project's main branch.
+
+```bash
+# Fetch the latest changes from the base remote
+git fetch base
+
+# Merge the base/main branch into your current branch
+# The --allow-unrelated-histories flag is necessary because your project
+# and base do not share a common Git history.
+git merge base/main --allow-unrelated-histories
+```
+
+This will bring all the files from `base` into your project.
+
+## 3. Handle Merge Conflicts
+
+It is highly likely that you will encounter merge conflicts, especially for files that exist in both your project and `base` (e.g., `.gitignore`, `README.md`).
+
+When a merge conflict occurs, Git will pause the merge process and mark the conflicting files. To resolve them:
+
+1.  **Identify Conflicting Files:** Run `git status` to see a list of files with conflicts. They will be marked as "unmerged".
+
+2.  **Open the Files:** Open each conflicting file in your code editor. You will see conflict markers:
+
+    ```
+    <<<<<<< HEAD
+    # Your existing .gitignore content
+    node_modules/
+    =======
+    # .gitignore content from base
+    .vscode/
+    .devcontainer/
+    >>>>>>> base/main
+    ```
+
+3.  **Resolve the Conflicts:** Edit the file to keep the version you want. You might want to keep your version, the `base` version, or a combination of both. For example, in the `.gitignore` conflict above, you would likely want to combine the entries from both:
+
+    ```
+    # Combined .gitignore
+    node_modules/
+    .vscode/
+    .devcontainer/
+    ```
+
+    Remove the `<<<<<<<`, `=======`, and `>>>>>>>` markers after editing.
+
+4.  **Stage the Resolved Files:** After resolving the conflicts in a file, stage it using `git add`:
+
+    ```bash
+    git add .gitignore
+    ```
+
+5.  **Commit the Merge:** Once you have resolved all conflicts and staged all the conflicting files, commit the merge:
+
+    ```bash
+    git commit
+    ```
+
+    A pre-populated commit message will appear. You can keep it as is or modify it.
+
+## 4. Create a Pull Request
+
+After the merge is complete and all conflicts are resolved, you should push the changes to your own repository and create a Pull Request (PR). This allows your team to review the changes before they are integrated into the main branch.
+
+1.  **Push Your Branch:**
+
+    ```bash
+    git push origin your-branch-name
+    ```
+
+2.  **Open a Pull Request:** Go to your repository on GitHub. You will see a prompt to create a new Pull Request from the branch you just pushed. Click on it, fill out the details, and create the PR.
+
+By following these steps, you can successfully merge the `base` repository into your existing project and manage any conflicts that arise.