diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 389cb2f..2cfce5c 100644 --- a/CONTRIBUTING.md +++ b/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 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. diff --git a/docs/web-ui-workflow.md b/docs/web-ui-workflow.md new file mode 100644 index 0000000..973d0f5 --- /dev/null +++ b/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.