Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: simplified the merge conflicts section #232

Merged
merged 4 commits into from
Dec 11, 2023
Merged

fix: simplified the merge conflicts section #232

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ea1f3b8
fix: Clarify resolving merge conflicts section
jdwilkin4 Dec 10, 2023
5111b97
Update docs/contributing/technical/resolve-merge-conflicts.md
jdwilkin4 Dec 11, 2023
269705d
fix: clearing up upstream directions
jdwilkin4 Dec 11, 2023
799aaa2
docs: add punctuations and fix capitalization for consistency
adiati98 Dec 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 39 additions & 98 deletions docs/contributing/technical/resolve-merge-conflicts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,138 +6,79 @@ keywords:
- "resolve merge conflicts"
---

You'll likely encounter merge conflicts when opening a pull request, as the release process generally updates `npm-shrinkwrap.json`.
When you are working on any of the OpenSauced repositories, you might run into a merge conflict. A merge conflict occurs when multiple conflicting changes are made to the same line in a file. Merge conflicts happen the most when you open a pull request, as the release process generally updates `npm-shrinkwrap.json`.

To better illustrate the commands listed here, we will use commits and screenshots from [open-sauced#1078](https://github.com/open-sauced/open-sauced/pull/1078).
In this guide, we will talk about how to resolve merge conflicts and how to keep your branch up to date.

## Repository Setup
## How to Check for Merge Conflicts Locally

Fork and clone the project using the `gh` command line interface:
If you are actively working on a change to an OpenSauced repository, you can check for potential merge conflicts by running a few commands in the terminal.

```shell
gh repo clone 0-vortex/open-sauced
```

Running `git remote -v` will output:

```shell
origin [email protected]:0-vortex/open-sauced.git (fetch)
origin [email protected]:0-vortex/open-sauced.git (push)
upstream [email protected]:open-sauced/open-sauced.git (fetch)
upstream [email protected]:open-sauced/open-sauced.git (push)
```

Fork and clone the project using the `git` command line interface:

```shell
git clone [email protected]:0-vortex/open-sauced.git
```
1. Make sure you are on the correct branch where the changes are being made

Running `git remote -v` will output:

```shell
origin [email protected]:0-vortex/open-sauced.git (fetch)
origin [email protected]:0-vortex/open-sauced.git (push)
```bash
cd app
git checkout <your-branch>
```

As an additional step for this tutorial, we need to add the `upstream` remote:
2. Fetch the latest changes from the OpenSauced main repository.

```shell
git remote add upstream [email protected]:open-sauced/open-sauced.git
```bash
git fetch upstream
jdwilkin4 marked this conversation as resolved.
Show resolved Hide resolved
```

## Update

First, get the default branch changes:
3. See the differences between your branch and the OpenSauced main branch

```shell
git fetch origin --recurse-submodules=no --progress --prune
git checkout main --
git fetch upstream --recurse-submodules=no --progress --prune
git merge upstream/main --no-stat -v
```bash
git diff <your-branch> upstream/main
jdwilkin4 marked this conversation as resolved.
Show resolved Hide resolved
```

## Merge with `upstream`

Then merge with the forked up-to-date `beta` (default branch):

```shell
git merge origin/main --no-ff -v
```

You will see something similar to:

![proper merge but results in conflicts](../../../static/img/contributing-resolve-merge-conflicts-merge-conflicts.png)
**NOTE**: Some of the OpenSauced repositories will use `main` for the main branch while others like the [app repository](https://github.com/open-sauced/app), will use `beta` for the main branch name.

## Review Changes
![git diff output review conflicts](../../../static/img/contributing-resolve-merge-conflicts-review-conflicts.png)

To see what the changes are, run the command below:
**NOTE**: If you have already opened up a pull request, then you can see if there is a conflict at the bottom of the PR. Even though it is possible to resolve conflicts through GitHub, it is best practice to resolve them locally.

```shell
git diff package.json
```

It will look like this:
![merge conflicts git message](../../../static/img/contributing-resolve-merge-conflicts-dont-do.png)

![review merge conflicts](../../../static/img/contributing-resolve-merge-conflicts-review-conflicts.png)
## How to Resolve Merge Conflicts

## Resolve Conflicts
If you have merge conflicts, it is best to use a text editor to resolve them. Identify the conflicting files and open them up in your editor of choice. For the conflicting sections, you have an option to either keep the incoming changes, keep your changes or keep both sets of changes. The conflicting sections will be marked with `<<<<<<<`, `=======`, and `>>>>>>>` symbols.

Since this pull request does not modify the `package.json` file, it is safe to fast-forward the changes from `origin/main`:

```shell
# overwrite with origin/main changes
git show :3:package.json > package.json
```
Here is a [guide](https://dev.to/adiatiayu/how-to-resolve-merge-conflicts-using-the-merge-editor-feature-on-vs-code-pic) for an in depth walkthrough of the process. Once you have resolved all of the conflicts, then you can stage, commit and push your changes to your branch.
jdwilkin4 marked this conversation as resolved.
Show resolved Hide resolved

A more traditional way of doing the same thing is:

```shell
# make a local copy of all changes and use --theirs
# --theirs strategy overwrite with origin/main changes
git show :1:package.json > base.package.json
git show :2:package.json > branch.package.json
git show :3:package.json > head.package.json
git merge-file -p --theirs \
branch.package.json base.package.json head.package.json > package.json
```bash
git status
git add .
git commit -m "fix: resolving merge conflicts"
git push
```

## Commit Changes
## How to Keep Your Branch Updated
jdwilkin4 marked this conversation as resolved.
Show resolved Hide resolved

Not making any assumptions about editor preferences, running this will open the configured editor with a default commit message:
It is common for your branch to fall behind the main repository's branch. So it is important to keep it up to date as you are contributing.

```shell
git commit
```
### Using GitHub

That should look like this:
To update your branch on GitHub, you can go to your forked copy of the project and click on `Sync fork` and then the `Update branch` button.

![commit merge message](../../../static/img/contributing-resolve-merge-conflicts-commit-message.png)
![syncing your branch on GitHub](../../../static/img/sync-branch-GH.png)

## Push Changes
### Using Git

One more security check to make sure your branch has not diverged and push:
To update your branch using Git and the terminal, you can use the following command:

```shell
git status
git push
```bash
git pull upstream <main-branch-name>
jdwilkin4 marked this conversation as resolved.
Show resolved Hide resolved
```

It should look something like this:

![push updated pr](../../../static/img/contributing-resolve-merge-conflicts-merge-success.png)

## Review Your Pull Request

The result of the above commands can be viewed at [283ff8cd788c550309ff0d1d5a9a5a97ec0731b2](https://github.com/open-sauced/open-sauced/pull/1078/commits/283ff8cd788c550309ff0d1d5a9a5a97ec0731b2).

GitHub will conveniently display only your merge conflict changes:
**NOTE**: Some of the OpenSauced repositories will use `main` for the main branch while others like the [app repository](https://github.com/open-sauced/app), will use `beta` for the main branch name.

![view merge commit](../../../static/img/contributing-resolve-merge-conflicts-view-merge-commit.png)
## Reviewing Your Pull Request

And it's ready to merge:
Once you have pushed up your changes, you can create a pull request. Under the files changed tab, you will see all of the recent changes including all conflicts resolved.
jdwilkin4 marked this conversation as resolved.
Show resolved Hide resolved

![ready to merge](../../../static/img/contributing-resolve-merge-conflicts-ready-to-merge.png)
![files changed tab on GitHub](../../../static/img/files-changed-tab.png)

## Dependency Updates

Expand Down
17 changes: 3 additions & 14 deletions sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,7 @@ module.exports = {
type: "category",
label: "Getting Started",
collapsed: false,
items: [
"welcome/opensauced-intro",
"welcome/glossary",
"welcome/faqs"
],
items: ["welcome/opensauced-intro", "welcome/glossary", "welcome/faqs"],
},
{
type: "category",
Expand Down Expand Up @@ -48,10 +44,7 @@ module.exports = {
type: "category",
label: "Community",
collapsed: false,
items: [
"community/welcome-to-the-community",
"community/100-days-of-oss"
],
items: ["community/welcome-to-the-community", "community/100-days-of-oss"],
},
{
type: "category",
Expand Down Expand Up @@ -120,11 +113,7 @@ module.exports = {
type: "category",
label: "Technical Guide",
collapsed: true,
items: [
"contributing/technical/introduction-to-storybook",
"contributing/technical/setup-repo-with-git",
"contributing/technical/resolve-merge-conflicts",
],
items: ["contributing/technical/setup-repo-with-git", "contributing/technical/resolve-merge-conflicts"],
},
],
},
Expand Down
Binary file added static/img/files-changed-tab.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/sync-branch-GH.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading