|
| 1 | +# Conflict Analysis Methodology |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document explains how the PR conflict analysis was performed and how to reproduce it. |
| 6 | + |
| 7 | +## Tools Used |
| 8 | + |
| 9 | +1. **GitHub CLI (`gh`)** - For fetching PR data from GitHub API |
| 10 | +2. **Git** - For comparing branch differences |
| 11 | +3. **Python 3** - For data processing and analysis |
| 12 | + |
| 13 | +## Analysis Process |
| 14 | + |
| 15 | +### Step 1: Fetch Open PRs |
| 16 | + |
| 17 | +```bash |
| 18 | +gh pr list --limit 25 --json number,title,state,files,author --repo TheSuperHackers/GeneralsGameCode |
| 19 | +``` |
| 20 | + |
| 21 | +This fetches: |
| 22 | +- PR number and title |
| 23 | +- List of all files changed in each PR |
| 24 | +- Author information |
| 25 | +- Current state (open/closed) |
| 26 | + |
| 27 | +### Step 2: Get Files Changed in Unification Branches |
| 28 | + |
| 29 | +For each unification branch: |
| 30 | + |
| 31 | +```bash |
| 32 | +git diff --name-only main..bobtista/unify-common |
| 33 | +git diff --name-only main..bobtista/unify-gameclient |
| 34 | +git diff --name-only main..bobtista/unify-gamelogic |
| 35 | +git diff --name-only main..bobtista/unify-network |
| 36 | +``` |
| 37 | + |
| 38 | +This gives us the complete list of files being moved/changed in each unification effort. |
| 39 | + |
| 40 | +### Step 3: Find Overlapping Files |
| 41 | + |
| 42 | +For each unification branch, find files that appear in BOTH: |
| 43 | +- The unification branch changes |
| 44 | +- Any open PR's changes |
| 45 | + |
| 46 | +If a file appears in both, it's a **potential conflict**. |
| 47 | + |
| 48 | +### Step 4: Categorize by Risk Level |
| 49 | + |
| 50 | +**🟢 Low Risk**: Only `CMakeLists.txt` files conflict |
| 51 | +- These are routine build configuration conflicts |
| 52 | +- Easy to merge by combining both sets of changes |
| 53 | + |
| 54 | +**🟡 Medium Risk**: 1-3 files conflict |
| 55 | +- Usually straightforward to resolve |
| 56 | +- May require reviewing the specific changes |
| 57 | + |
| 58 | +**🔴 High Risk**: 4+ files conflict |
| 59 | +- Significant overlap with other work |
| 60 | +- Requires coordination with PR author |
| 61 | +- May need to merge one PR first, then rebase the other |
| 62 | + |
| 63 | +## How to Reproduce |
| 64 | + |
| 65 | +### Prerequisites |
| 66 | + |
| 67 | +```bash |
| 68 | +# Install GitHub CLI (macOS) |
| 69 | +brew install gh |
| 70 | + |
| 71 | +# Login to GitHub |
| 72 | +gh auth login |
| 73 | + |
| 74 | +# Clone the repository |
| 75 | +git clone https://github.com/TheSuperHackers/GeneralsGameCode.git |
| 76 | +cd GeneralsGameCode |
| 77 | + |
| 78 | +# Fetch all branches |
| 79 | +git fetch --all |
| 80 | +``` |
| 81 | + |
| 82 | +### Run the Analysis |
| 83 | + |
| 84 | +```bash |
| 85 | +# Option 1: Use the provided script |
| 86 | +python3 scripts/analyze_pr_conflicts.py |
| 87 | + |
| 88 | +# Option 2: Manual step-by-step |
| 89 | +# See "Manual Analysis" section below |
| 90 | +``` |
| 91 | + |
| 92 | +### Script Output |
| 93 | + |
| 94 | +The script produces: |
| 95 | +1. **Console output**: Formatted report with statistics and details |
| 96 | +2. **JSON file**: `pr_conflict_analysis.json` with complete data for further processing |
| 97 | + |
| 98 | +## Manual Analysis (Without Script) |
| 99 | + |
| 100 | +If you want to manually check conflicts: |
| 101 | + |
| 102 | +### 1. Get Open PRs |
| 103 | + |
| 104 | +```bash |
| 105 | +gh pr list --limit 25 --json number,title,files --repo TheSuperHackers/GeneralsGameCode > prs.json |
| 106 | +``` |
| 107 | + |
| 108 | +### 2. Check Specific File Conflicts |
| 109 | + |
| 110 | +```bash |
| 111 | +# See which PRs touch a specific file |
| 112 | +cat prs.json | jq '.[] | select(.files[].path | contains("Language.h")) | {number, title}' |
| 113 | + |
| 114 | +# See all files in a specific PR |
| 115 | +gh pr view 1703 --json files --jq '.files[].path' |
| 116 | +``` |
| 117 | + |
| 118 | +### 3. Compare Your Branch |
| 119 | + |
| 120 | +```bash |
| 121 | +# See what files your branch changes |
| 122 | +git diff --name-only main..bobtista/unify-common |
| 123 | + |
| 124 | +# Check if a specific file conflicts with open PRs |
| 125 | +FILE="Generals/Code/GameEngine/Include/Common/Language.h" |
| 126 | +git diff --name-only main..bobtista/unify-common | grep "$FILE" && echo "File in your branch" |
| 127 | +gh pr list --json number,files --jq ".[] | select(.files[].path == \"$FILE\") | .number" |
| 128 | +``` |
| 129 | + |
| 130 | +## Understanding the Results |
| 131 | + |
| 132 | +### Example Conflict |
| 133 | + |
| 134 | +``` |
| 135 | +Branch: bobtista/unify-common |
| 136 | +PR #1739: refactor(language.h): remove unused and redundant defines |
| 137 | +Conflicting files (1): |
| 138 | + - Generals/Code/GameEngine/Include/Common/Language.h |
| 139 | +``` |
| 140 | + |
| 141 | +**Interpretation:** |
| 142 | +- Your `unify-common` branch moves/modifies `Language.h` |
| 143 | +- PR #1739 also modifies `Language.h` |
| 144 | +- If both merge, there WILL be a conflict |
| 145 | + |
| 146 | +**Resolution Options:** |
| 147 | +1. Merge PR #1739 first, then rebase your branch |
| 148 | +2. Exclude `Language.h` from your unification |
| 149 | +3. Coordinate with PR author to merge yours first, they rebase theirs |
| 150 | + |
| 151 | +### CMakeLists.txt Conflicts |
| 152 | + |
| 153 | +``` |
| 154 | +PR #1594: feat(crashdump): Add crash dump functionality |
| 155 | +Conflicting files (1): |
| 156 | + - Core/GameEngine/CMakeLists.txt |
| 157 | +``` |
| 158 | + |
| 159 | +**Why low risk:** |
| 160 | +- CMakeLists.txt conflicts happen because both PRs add new files/dependencies |
| 161 | +- Resolution is simple: Keep both changes |
| 162 | +- No code logic conflicts |
| 163 | + |
| 164 | +## Limitations |
| 165 | + |
| 166 | +### What This Analysis Catches |
| 167 | + |
| 168 | +✅ File-level conflicts (same file modified in both) |
| 169 | +✅ Moved/renamed files |
| 170 | +✅ Added/deleted files |
| 171 | + |
| 172 | +### What This Analysis Misses |
| 173 | + |
| 174 | +❌ Semantic conflicts (code logic that breaks across files) |
| 175 | +❌ Build dependency conflicts |
| 176 | +❌ Header include path changes |
| 177 | +❌ API/interface changes that affect other code |
| 178 | + |
| 179 | +### False Positives |
| 180 | + |
| 181 | +Some "conflicts" might not actually conflict: |
| 182 | +- Changes to different parts of the same file |
| 183 | +- Changes that are compatible/complementary |
| 184 | +- One PR adds code, other removes different code |
| 185 | + |
| 186 | +**Always review the actual changes, not just file names!** |
| 187 | + |
| 188 | +## Recommendations for Use |
| 189 | + |
| 190 | +### Before Creating a Large Refactor/Unification PR |
| 191 | + |
| 192 | +1. Run this analysis |
| 193 | +2. Identify high-risk conflicts |
| 194 | +3. Coordinate with those PR authors |
| 195 | +4. Consider excluding conflicting files temporarily |
| 196 | + |
| 197 | +### After Running Analysis |
| 198 | + |
| 199 | +1. **Post results** in your PR description |
| 200 | +2. **Tag affected authors** in comments |
| 201 | +3. **Propose a merge order** to maintainers |
| 202 | +4. **Offer to help** with rebasing |
| 203 | + |
| 204 | +### For Maintainers |
| 205 | + |
| 206 | +1. Use this to plan merge order |
| 207 | +2. Prioritize by: |
| 208 | + - Bug fixes (highest priority) |
| 209 | + - Features (merge or delay?) |
| 210 | + - Refactors (can usually wait) |
| 211 | +3. Batch similar PRs together |
| 212 | + |
| 213 | +## Example Workflow |
| 214 | + |
| 215 | +```bash |
| 216 | +# 1. Create your unification branch |
| 217 | +git checkout -b unify-my-feature |
| 218 | + |
| 219 | +# 2. Before making changes, run analysis |
| 220 | +python3 scripts/analyze_pr_conflicts.py |
| 221 | + |
| 222 | +# 3. Review conflicts in your area |
| 223 | +# - If few/no conflicts: Proceed |
| 224 | +# - If many conflicts: Coordinate with team |
| 225 | + |
| 226 | +# 4. Make your changes, excluding problem files |
| 227 | + |
| 228 | +# 5. Create PR with analysis in description |
| 229 | + |
| 230 | +# 6. Update PR as other PRs merge |
| 231 | +git fetch --all |
| 232 | +git rebase origin/main |
| 233 | +python3 scripts/analyze_pr_conflicts.py # Re-run to see new state |
| 234 | +``` |
| 235 | + |
| 236 | +## Data Storage |
| 237 | + |
| 238 | +The script saves detailed JSON output: |
| 239 | + |
| 240 | +```json |
| 241 | +{ |
| 242 | + "branches": { |
| 243 | + "bobtista/unify-common": ["file1.h", "file2.cpp", ...] |
| 244 | + }, |
| 245 | + "conflicts": { |
| 246 | + "bobtista/unify-common": { |
| 247 | + "1739": { |
| 248 | + "title": "refactor(language.h): ...", |
| 249 | + "author": "Skyaero42", |
| 250 | + "files": ["Generals/Code/GameEngine/Include/Common/Language.h"] |
| 251 | + } |
| 252 | + } |
| 253 | + }, |
| 254 | + "risk_categories": { |
| 255 | + "low": [...], |
| 256 | + "medium": [...], |
| 257 | + "high": [...] |
| 258 | + } |
| 259 | +} |
| 260 | +``` |
| 261 | + |
| 262 | +You can use this JSON for: |
| 263 | +- Custom analysis |
| 264 | +- Integration with CI/CD |
| 265 | +- Tracking over time |
| 266 | +- Automated notifications |
| 267 | + |
| 268 | +## Questions? |
| 269 | + |
| 270 | +If you have questions about the methodology: |
| 271 | +1. Read the script source: `scripts/analyze_pr_conflicts.py` |
| 272 | +2. Check the GitHub CLI docs: https://cli.github.com/manual/ |
| 273 | +3. Ask in the PR discussion |
| 274 | + |
| 275 | +## Credits |
| 276 | + |
| 277 | +Analysis methodology developed by @bobtista for PR #1736. |
| 278 | + |
| 279 | + |
| 280 | + |
0 commit comments