Skip to content

Commit 1d41316

Browse files
Mounil2005Mounil2005
authored
docs: Update rebasing.md and add merge_conflicts.md (#347)
Signed-off-by: Mounil <[email protected]>
1 parent 0551f37 commit 1d41316

File tree

3 files changed

+231
-14
lines changed

3 files changed

+231
-14
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
2828
- consumeLargeData() function in StatefulContract
2929
- example script for Token Airdrop
3030
- added variables directly in the example script to reduce the need for users to supply extra environment variables.
31+
- Added new `merge_conflicts.md` with detailed guidance on handling conflicts during rebase.
3132

3233
### Changed
3334
- Extract _build_proto_body() from build_transaction_body() in every transaction
@@ -38,6 +39,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
3839
- Switched Mirror Node endpoints used by SDK to secure ones instead of deprecated insecure endpoints (shut down on Aug 20th, see [Hedera blogpost](https://hedera.com/blog/updated-deprecation-of-the-insecure-hedera-consensus-service-hcs-mirror-node-endpoints))
3940
- Update protobuf dependency from 5.28.1 to 5.29.1
4041
- Update grpcio dependency from 1.68.1 to 1.71.2
42+
- Updated `rebasing.md` with clarification on using `git reset --soft HEAD~<n>` where `<n>` specifies the number of commits to rewind.
4143

4244
### Fixed
4345
- Unit test compatibility issues when running with UV package manager

‎docs/sdk_developers/merge_conflicts.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
## Handling Conflicts
2+
3+
Conflicts are common if main has updates to the files you are working on. In which case, you'll have to run a rebase.
4+
5+
If you are warned of a conflict:
6+
7+
- In VS Code: open the conflicted files and use the built-in conflict resolution.
8+
9+
### 1. See which files are conflicted
10+
```bash
11+
git status
12+
```
13+
14+
### 2. Resolve conflicts manually
15+
You will see sections like:
16+
17+
```text
18+
<<<<<<< HEAD
19+
code from main
20+
=======
21+
your branch’s code
22+
>>>>>>> mybranch
23+
```
24+
25+
1. Decide what the final code should be.
26+
27+
2. Sometimes keep main, sometimes your branch, sometimes both.
28+
29+
### 3. Resolving conflicts in VS Code (recommended):
30+
VS Code provides an easier 3-pane interface for resolving conflicts:
31+
32+
-> Incoming Change → code from main (left/top)
33+
34+
-> Current Change → code from your branch (right/top)
35+
36+
-> Result → the lower/third pane, where you create the final merged file
37+
38+
#### Steps to resolve:
39+
40+
1. Open the conflicted file in VS Code.
41+
42+
2. Look at both the Incoming Change and Current Change panels.
43+
44+
3. In the Result (lower pane), edit the file so it contains the correct final version.
45+
46+
-> Sometimes keep Incoming (main)
47+
48+
-> Sometimes keep Current (your branch)
49+
50+
-> Often, combine both parts.
51+
52+
4. Save the file. If the conflict is resolved correctly, VS Code will mark it as fixed.
53+
54+
5. If there are more conflicts, VS Code will automatically move you to the next one. Repeat until no conflicts remain.
55+
56+
⚠️ Do NOT just click “Accept All Incoming” or “Accept All Current” — that usually deletes important code.
57+
58+
## After fixing conflicts:
59+
60+
### 4. Stage the resolved files
61+
```bash
62+
git add .
63+
```
64+
65+
### 5.Continue the rebase
66+
```bash
67+
git rebase --continue
68+
```
69+
Repeat until all conflicts are resolved.
70+
71+
### 6. After Rebase is Completed
72+
73+
Once the rebase finishes successfully:
74+
75+
- Your commits may look “different” (new commit hashes) — this is expected, since rebase rewrites history.
76+
- If you already have an open Pull Request, you will need to update it with a **force push**, before pushing, double-check that your commits are both DCO signed and GPG verified:
77+
```bash
78+
git log --show-signature
79+
```
80+
then:
81+
```bash
82+
git push --force
83+
```
84+
85+
**Tip**: To be safe, create a backup branch before force pushing:
86+
```bash
87+
git checkout -b mybranch-backup
88+
```
89+
90+
91+
## Common issues
92+
Message: “No changes – did you forget to use git add?”
93+
→ This means you resolved the conflicts but forgot to stage them. Run git add . and try again.
94+
95+
Message: “Are you sure you want to continue with conflicts?”
96+
→ This means some conflicts are still unresolved or you did not save the files properly.
97+
Double-check your files in VS Code, make sure they are saved, and resolve any remaining conflict markers (<<<<<<<, =======, >>>>>>>).
98+
99+
100+
## If you need to stop
101+
```bash
102+
git rebase --abort
103+
```
104+
105+
**Tip**: At each conflict: resolve → save → stage → continue. Repeat until all conflicts are gone.
106+
107+
# What NOT to do
108+
1. ❌ Do not run git merge main
109+
→ This creates messy merge commits. Always rebase instead.
110+
111+
2. ❌ Do not merge into your local main
112+
→ Keep main as a clean mirror of upstream/main.
113+
114+
3. ❌ Do not open PRs from your fork’s main
115+
→ Always create a feature branch for your changes.
116+
117+
At each conflict instance, you'll have to repeat: fix the conflict, stage the files and continue rebasing.
118+
119+
## Recovery Tips:
120+
121+
- Undo the last rebase commit, but keep changes staged (while still in rebase):
122+
If you are in the middle of a rebase and realize the last step went wrong, you can undo it while keeping changes staged:
123+
```bash
124+
git reset --soft HEAD~i
125+
```
126+
127+
Note: The number after HEAD~ refers to how many commits you want to go back.
128+
129+
For example:
130+
HEAD~1 → go back 1 commit
131+
HEAD~3 → go back 3 commits
132+
HEAD~5 → go back 5 commits
133+
134+
### If you are completely stuck
135+
Sometimes a rebase can get too messy to fix conflict by conflict. In that case, it’s often easier to start fresh:
136+
137+
1. Abort the rebase to stop where you are:
138+
```bash
139+
git rebase --abort
140+
```
141+
142+
2. Reset your branch to match upstream/main:
143+
``` bash
144+
git checkout main
145+
git reset --hard upstream/main
146+
git checkout mybranch
147+
git rebase upstream/main -S
148+
```
149+
150+
⚠️ Use git stash only if you really want to save some local changes that aren’t yet committed. In most cases, if the rebase is failing, it’s safer to abort or reset rather than reapplying a stash of broken work.
151+
152+
153+
- To check commit signatures (verified status):
154+
```bash
155+
git log --pretty="%h %G? %aN %s"
156+
```
157+
-> G = good signature (verified)
158+
-> B = bad signature
159+
-> U = unsigned commit
160+
-> N = no signature
161+
162+
- To check for "Signed-off-by" lines:
163+
This shows commits along with their sign-off lines, helping you verify compliance with DCO (Developer Certificate of Origin).
164+
```bash
165+
git log --pretty="%h %s%n%b" | grep -B1 -A0 "Signed-off-by:"
166+
```

‎docs/sdk_developers/rebasing.md‎

Lines changed: 63 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Rebasing (Hiero Python SDK)
1+
# Keeping Your Branch Up to Date with Main (Hiero Python SDK)
22

33
If you have forked the Hiero Python SDK, created your own branch, and now need to sync it with the latest changes from main in the original repository, follow these steps.
44

@@ -11,8 +11,26 @@ Only do this once per repository clone.
1111
git remote add upstream https://github.com/hiero-ledger/hiero-sdk-python.git
1212
```
1313

14+
## Quick Cheatsheet
15+
- Sync main:
16+
```bash
17+
git checkout main
18+
git fetch upstream
19+
git pull upstream main
20+
```
21+
22+
- Rebase branch:
23+
```bash
24+
git checkout mybranch
25+
git rebase main -S
26+
```
27+
28+
1429
## Update Your Main
1530

31+
Your local main should always be an exact copy of the original repo’s main.
32+
Never commit directly to it. Never open PRs from it.
33+
1634
Update your main easily with the latest python sdk main by visiting your repository https://github.com/your_name/hiero_sdk_python and clicking the sync fork button which is a few lines from the top near the right.
1735

1836
Alternatively run these commands every time you want to update your branch with the latest main.
@@ -42,31 +60,62 @@ It is necessary to run these commands if main updates with changes that impact w
4260
```bash
4361
git checkout mybranch
4462
```
63+
## Check Commit Signatures Before Rebasing
4564

46-
### 2. Rebase your branch on top of the updated main
47-
# Rebase = cleaner history, your commits appear on top of main.
65+
Before starting a rebase, make sure your commits are correctly signed. Unsigned commits may cause CI checks to fail after you push your branch.
66+
67+
#### 1. Verify existing commits
68+
69+
Run one of the following commands:
70+
71+
-> To check DCO (Developer Certificate of Origin) sign-off:
4872
```bash
49-
git rebase main -S
73+
git log --pretty=format:"%h %s %b" | grep "Signed-off-by"
74+
```
75+
76+
✅ Each commit should have a Signed-off-by: Your Name <email> line.
77+
78+
-> To check GPG-signed commits:
79+
```bash
80+
git log --show-signature
5081
```
5182

52-
## Handling Conflicts
83+
✅ Look for gpg: Good signature in the output.
5384

54-
Conflicts are common if main has updates to the files you are working on. In which case, you'll have to run a rebase.
85+
-> Quick check for both:
86+
```bash
87+
git log --pretty=format:"%h %s %G?"
88+
```
5589

56-
If you are warned of a conflict:
90+
-> Legend:
5791

58-
- In VS Code: open the conflicted files and use the built-in conflict resolution.
92+
G = Good (valid signature)
93+
B = Bad (invalid signature)
94+
U = Unknown (not signed)
5995

60-
After fixing conflicts:
96+
#### 2.Project Requirement:
97+
This project requires both DCO and GPG signed commits.
6198

62-
Stage the files:
99+
If you don’t have GPG keys set up, use -s for DCO sign-off.
100+
101+
If you do have GPG keys configured, prefer -S for extra verification.
102+
103+
**Tip**: Always use this to be safe:
63104
```bash
64-
git add .
105+
git commit -s -S -m "Your-commit-message"
65106
```
66-
then continue rebasing:
107+
108+
### 2. Rebase your branch on top of the updated main
109+
# Rebase = cleaner history, your commits appear on top of main.
110+
67111
```bash
68-
git rebase --continue
112+
git rebase main -S
69113
```
70-
At each conflict instance, you'll have to repeat: fix the conflict, stage the files and continue rebasing.
114+
115+
Note: The -S ensures your commits are signed.
116+
117+
## Handling Conflicts:
118+
If conflicts occur during rebase, See [merge_conflicts.md](merge_conflicts.md) for detailed guidance.
119+
71120

72121
**Tip**: Always sync your branch before opening or updating a Pull Request to reduce review friction and avoid merge conflicts.

0 commit comments

Comments
 (0)