Skip to content

Commit 5841133

Browse files
docs: add guide for resolving CHANGELOG.md conflicts using GitHub web editor (hiero-ledger#1601)
Signed-off-by: Siddhartha Ganguly <gangulysiddhartha22@gmail.com> Signed-off-by: gangulysiddhartha22-cmyk <gangulysiddhartha22@gmail.com> Signed-off-by: exploreriii <133720349+exploreriii@users.noreply.github.com> Co-authored-by: exploreriii <133720349+exploreriii@users.noreply.github.com>
1 parent 31e0cb8 commit 5841133

2 files changed

Lines changed: 46 additions & 2 deletions

File tree

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
2525
- Formatted client_test.py using Black.
2626

2727
### Added
28+
- Added guide for resolving CHANGELOG.md conflicts using GitHub's web editor (`#1591`)
2829

2930
- Added Windows setup guide for SDK developers (`docs/sdk_developers/training/setup/setup_windows.md`) with PowerShell installation instructions. (#1570)
3031
- Added a beginner assignment guard that requires completion of a Good First Issue. (#1484)

docs/sdk_developers/merge_conflicts.md

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ Merge conflicts are caused by working on out-dated versions of the codebase, or
77
## Table of Contents
88

99
- [Handling Conflicts](#handling-conflicts)
10-
- [Step by Step Guide to Resolve Merge Conflicts](#step-by-step-guide-to-resolve-merge-conflicts)
10+
- [Resolving CHANGELOG.md Conflicts Using GitHub's Web Editor](#resolving-changelogmd-conflicts-using-githubs-web-editor)
11+
- [Step-by-Step Guide to Resolve Merge Conflicts Locally](#step-by-step-guide-to-resolve-merge-conflicts-locally)
1112
- [1. See which files are conflicted](#1-see-which-files-are-conflicted)
1213
- [2. Understand what conflicts](#2-understand-what-conflicts)
1314
- [3. Decide what the final code should be](#3-decide-what-the-final-code-should-be)
@@ -24,13 +25,55 @@ Merge conflicts are caused by working on out-dated versions of the codebase, or
2425
- [Common issues](#common-issues)
2526
- [If you need to stop](#if-you-need-to-stop)
2627
- [What NOT to do](#what-not-to-do)
28+
- [When to Use This Method](#when-to-use-this-method)
29+
- [Steps](#steps)
2730
- [Recovery Tips](#recovery-tips)
2831
- [If you are completely stuck](#if-you-are-completely-stuck)
2932
- [Helpful Resources](#helpful-resources)
3033

3134

35+
## Resolving CHANGELOG.md Conflicts Using GitHub's Web Editor
3236

33-
## Step by Step Guide to Resolve Merge Conflicts
37+
Changelog conflicts in CHANGELOG.md are very common in this repository because multiple pull requests frequently add new entries to the "Unreleased" section at the same time.
38+
39+
For these conflicts, there is a much simpler alternative to the full local rebase process: you can resolve them directly in your Pull Request on GitHub using the built-in web editor. No local setup or force push is required.
40+
41+
**Strong Recommendation**: Use the local VS Code rebase method (described below) to ensure full signing compliance. Use the web editor only if you are prepared to amend and re-sign the resolution commit locally afterward.
42+
43+
### When to Use This Method
44+
45+
- The conflict is only (or primarily) in `CHANGELOG.md`.
46+
- You want to keep both sets of changes — this is almost always the correct choice for changelogs, as they are designed to accumulate all entries over time.
47+
48+
**Important**: The warnings above about not blindly accepting changes apply to code files. For CHANGELOG.md, "accepting both" is safe and recommended.
49+
50+
### Steps
51+
52+
1. In your PR, go to **Files changed** and scroll to the bottom. In the merge‑conflict banner, click **Resolve conflicts** to open the web editor.
53+
2. In GitHub's web-based editor:
54+
- Conflicted sections are highlighted (usually in red/yellow).
55+
- You'll see **Incoming change** (from main) and **Current change** (from your branch) marked in red/highlighted areas.
56+
57+
3. **For a changelog conflict**:
58+
- Click **Accept both** (if the button is available) — this combines all the bullet-point entries perfectly.
59+
- If no "Accept both" button appears, manually remove the conflict markers (`<<<<<<< HEAD`, `=======`, `>>>>>>> your-branch`) and keep all entries from both sides.
60+
- Optionally, sort or group similar entries for neatness.
61+
62+
4. Once all conflicts are resolved, click **Mark as resolved** at the top of the editor.
63+
64+
5. You'll see a **Sign off and Commit** section:
65+
- Review your commit message
66+
- Click **Commit merge** (or **Commit directly to...** depending on your GitHub UI).
67+
68+
6. Your PR will update automatically, and the conflict will be resolved.
69+
70+
This method is especially beginner-friendly and avoids the more advanced local rebase steps.
71+
72+
For more details on GitHub's web-based editor, see: [The GitHub.dev web-based editor](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor).
73+
**Example**: See [PR `#1589`](https://github.com/hiero-ledger/hiero-sdk-python/pull/1589) for a real example of resolving a CHANGELOG.md conflict using this method.
74+
75+
76+
## Step-by-Step Guide to Resolve Merge Conflicts Locally
3477

3578
### 1. See which files are conflicted
3679
```bash

0 commit comments

Comments
 (0)