Skip to content

Commit 17a429d

Browse files
google-labs-jules[bot]google-labs-jules[bot]
committed
Refactor documentation for updating and merging base
This commit refactors the documentation for updating and merging `base`. - Creates two new guides for the two different scenarios of merging and updating. - Renames the guide files to be more descriptive. - Creates a new "Updating" section in the documentation index. - Corrects the git commands in the guides to be accurate for each scenario.
1 parent 9746f88 commit 17a429d

4 files changed

Lines changed: 302 additions & 104 deletions

File tree

‎docs/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,6 @@ This directory contains the documentation for the `base` project.
3030

3131
- [GitHub Codespaces](./development.codespaces.md) - Using Codespaces for cloud-based development.
3232
- [Docker Environment](./development.docker.md) - Using the included Docker setup.
33-
- [Merging `base`](./development.merging-base.md) - Incorporating `base` into an existing project.
3433
- [`package.json` Guide](./development.package-json.md) - Explanation of the `package.json` files.
3534
- [Using Prettier](./development.prettier.md) - Guide to installing and using Prettier.
3635
- [Prettier Workflow](./development.prettier-workflow.md) - Manually formatting code.
@@ -43,6 +42,11 @@ This directory contains the documentation for the `base` project.
4342

4443
- [Software Project Guide](./guides.software-project.md) - Using this repo as a foundation for a software project.
4544

45+
## Updating
46+
47+
- [Adding `base` to an Existing Repo](./updating.adding-base-to-existing-repo.md) - How to merge `base` into a project that was not created from the template.
48+
- [Syncing When `base` is Updated](./updating.syncing-your-repo-when-base-is-updated.md) - How to get the latest changes from `base` after you have already merged it.
49+
4650
## Project Management
4751

4852
- [Repository Badges](./project.badges.md) - How to use and create repository badges.

‎docs/development.merging-base.md‎

Lines changed: 0 additions & 103 deletions
This file was deleted.

‎docs/updating.adding-base-to-existing-repo.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Merging `base` Into an Existing Repository
2+
3+
This guide explains how to merge the `attogram/base` repository into your
4+
existing project.
5+
This is useful for incorporating the `base` features, such as the Docker
6+
environment and GitHub Actions, into a project that has already been started.
7+
8+
There are two ways to do this: an easy method using the GitHub web interface,
9+
and an advanced method using the command line on your local machine.
10+
11+
---
12+
13+
## Initial Merge
14+
15+
This section explains how to perform the first merge of `base` into your
16+
repository.
17+
18+
### Easy Method: Using GitHub Codespaces (Web-Based)
19+
20+
This method is recommended if you are not familiar with the command line or do
21+
not have Git installed on your machine.
22+
It uses GitHub Codespaces, which provides a development environment that runs
23+
in your browser.
24+
25+
1. **Navigate to Your Repository:**
26+
Go to the main page of your own existing repository on GitHub.
27+
28+
2. **Launch a New Codespace:**
29+
- Click the "**<> Code**" button.
30+
- Go to the "**Codespaces**" tab.
31+
- Click "**Create codespace on [your-branch-name]**".
32+
This will create a new development environment and open it in a new browser
33+
tab.
34+
35+
3. **Open the Terminal:**
36+
Once the Codespace has loaded, you will see a code editor and a file
37+
browser.
38+
You need to open the terminal:
39+
- Click the "hamburger" menu (☰) in the top-left corner.
40+
- Go to "**Terminal**" > "**New Terminal**".
41+
42+
4. **Run the Merge Commands:**
43+
In the terminal, you will now run a series of Git commands.
44+
These are the same commands as the advanced method, but you are running them
45+
in the browser instead of on your local machine.
46+
- **Add `base` as a remote:** This tells Git where to find the
47+
`attogram/base` repository.
48+
```bash
49+
git remote add base https://github.com/attogram/base.git
50+
```
51+
- **Fetch and merge `base`:** This downloads the `base` repository and
52+
merges it into your project.
53+
```bash
54+
git fetch base
55+
git merge base/main --allow-unrelated-histories
56+
```
57+
58+
5. **Handle Merge Conflicts:**
59+
If there are any merge conflicts, the Codespace will highlight the affected
60+
files in the file browser.
61+
- Click on a conflicted file to open it.
62+
- The editor will show you the conflicting changes with markers (`<<<<<<<`,
63+
`=======`, `>>>>>>>`).
64+
- You can use the buttons provided by the editor ("**Accept Current
65+
Change**", "**Accept Incoming Change**", etc.) to resolve the conflicts.
66+
- Once you have resolved the conflicts in a file, save it.
67+
68+
6. **Commit and Push the Changes:**
69+
- Go to the "**Source Control**" tab on the left-hand side (it looks like a
70+
branching icon).
71+
- Enter a commit message (e.g., "Merge attogram/base").
72+
- Click the checkmark icon to commit the changes.
73+
- Click the "**Sync Changes**" button to push the changes to your
74+
repository on GitHub.
75+
76+
7. **Create a Pull Request:**
77+
- Go back to your repository's main page on GitHub.
78+
- You will see a notification to create a Pull Request from your recently
79+
pushed changes.
80+
- Click on it, review the details, and create the PR.
81+
82+
### Advanced Method: Using the Command Line
83+
84+
This method is for users who are comfortable with the command line and have Git
85+
installed on their local machine.
86+
87+
1. **Add `base` as a Remote:**
88+
First, you need to add the `base` repository as a remote to your local Git
89+
repository.
90+
This allows you to fetch its branches and history.
91+
```bash
92+
git remote add base https://github.com/attogram/base.git
93+
```
94+
95+
2. **Fetch and Merge `base`:**
96+
Next, fetch the `base` repository's history and merge its `main` branch
97+
into your project's main branch.
98+
```bash
99+
git fetch base
100+
git merge base/main --allow-unrelated-histories
101+
```
102+
103+
3. **Handle Merge Conflicts:**
104+
It is highly likely that you will encounter merge conflicts.
105+
To resolve them:
106+
- Run `git status` to see a list of files with conflicts.
107+
- Open each conflicting file in your code editor and resolve the conflicts.
108+
- Stage the resolved files using `git add .`.
109+
- Commit the merge with `git commit`.
110+
111+
4. **Create a Pull Request:**
112+
After the merge is complete, push the changes to your repository and create
113+
a Pull Request.
114+
115+
---
116+
117+
## Keeping Your Repository Updated
118+
119+
After the initial merge, you can pull in future updates from `base` by running
120+
the following commands:
121+
122+
```bash
123+
git fetch base
124+
git merge base/main
125+
```
126+
127+
You may need to resolve merge conflicts again, just as you did during the
128+
initial merge.
129+
130+
---
131+
132+
## Alternative: Copying Files
133+
134+
If you only want to incorporate a small part of the `base` repository, like a
135+
specific workflow or configuration file, you can simply copy and paste it into
136+
your own project.
137+
138+
For example, you can copy the contents of the
139+
[`.github/`](https://github.com/attogram/base/tree/main/.github) directory to
140+
get the latest GitHub Actions workflows.
141+
142+
This method is simpler than a full merge, but you will need to manually update
143+
the files if you want to get future updates from `base`.

0 commit comments

Comments
 (0)