Pull request for issue #13

CONTRIBUTING.md

@@ -2,6 +2,8 @@
 
 This repository is a template. The contribution guide below is a generic placeholder. You should adapt it to the specific needs of your project.
 
+> **Note:** The guide below describes the standard `git`-based command-line workflow. For a simpler alternative that uses only the GitHub web interface, please see the [**GitHub Web UI Workflow**](./docs/web-ui-workflow.md) guide.
+
 ---
 
 ## Getting Started

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.

docs/web-ui-workflow.md

@@ -0,0 +1,75 @@
+# GitHub Web UI Workflow
+
+This document outlines how to contribute to this project using only the GitHub web interface, from making changes to merging a pull request. This is a great alternative for those who are not comfortable with the command line.
+
+## Table of Contents
+
+- [Creating a Pull Request from the Web UI](#creating-a-pull-request-from-the-web-ui)
+- [Merging a Pull Request from the Web UI](#merging-a-pull-request-from-the-web-ui)
+
+---
+
+## Creating a Pull Request from the Web UI
+
+You can make changes to files and create a pull request without leaving your browser. Here’s how:
+
+1.  **Navigate to the File:**
+    - Go to the file you want to edit in the repository. For example, if you want to fix a typo in the `README.md`, navigate to that file.
+
+2.  **Click the Edit Icon:**
+    - In the top right corner of the file view, you will see a pencil icon. Click it to start editing the file.
+
+    ![Edit file icon](https://docs.github.com/assets/cb-29824/images/help/repository/edit-file-icon.png)
+
+3.  **Make Your Changes:**
+    - The file will open in a text editor. Make your desired changes directly in the browser.
+
+4.  **Propose Changes:**
+    - Once you are done, scroll to the bottom of the page. You will see a "Propose changes" section.
+    - Write a clear and concise commit message that describes your change.
+    - You can also add an optional extended description.
+
+    ![Propose file change](https://docs.github.com/assets/cb-32008/images/help/repository/propose-file-change-form.png)
+
+5.  **Create the Pull Request:**
+    - After proposing the change, GitHub will automatically create a fork and a new branch for you.
+    - You will be taken to a new page to open a pull request. The commit message you wrote will be the title.
+    - Review the changes one last time and click the "Create pull request" button.
+
+That's it! You have successfully created a pull request.
+
+---
+
+## Merging a Pull Request from the Web UI
+
+If you are a maintainer of this project, you can merge pull requests directly from the GitHub interface.
+
+1.  **Go to the Pull Requests Tab:**
+    - In the main repository page, click on the "Pull requests" tab.
+
+2.  **Select the Pull Request:**
+    - Click on the pull request you want to merge.
+
+3.  **Review the Changes:**
+    - Look at the "Files changed" tab to review the proposed changes.
+    - Ensure that all automated checks (like CI) have passed.
+
+4.  **Merge the Pull Request:**
+    - If you are satisfied with the changes, go back to the "Conversation" tab.
+    - You will see a green "Merge pull request" button. Click it.
+
+    ![Merge pull request button](https://docs.github.com/assets/cb-33769/images/help/pull_requests/merge-pull-request-button.png)
+
+5.  **Confirm the Merge:**
+    - A confirmation box will appear. You can edit the commit message if you wish.
+    - Click "Confirm merge" to complete the process. The branch will be merged into the `main` branch.
+
+### Merge Options
+
+GitHub provides a few different ways to merge:
+
+- **Create a merge commit:** This is the default option. It keeps all the commits from the branch and adds them to the history of the `main` branch.
+- **Squash and merge:** This combines all the commits from the branch into a single commit on the `main` branch. This is useful for keeping the project history clean.
+- **Rebase and merge:** This adds the commits from the branch onto the `main` branch without a merge commit. This results in the cleanest history, but can be more complex to manage.
+
+You can choose the option that best fits the project's workflow.