explorer-monorepo/docs/PR_WORKFLOW_RECOMMENDATION.md

# Pull Request Workflow Recommendation

## Should We Use Submodules?

**Answer: NO** - Submodules are **NOT recommended** for PR work.

### Why Not Submodules?

1. **Submodules are for dependencies**: They're designed to track specific versions of external code within your project
2. **Awkward for PRs**: Working within a submodule to create PRs is cumbersome
3. **Version locking**: Submodules lock to specific commits, making it harder to work with latest code
4. **Complex workflow**: Requires submodule updates and nested git operations

### Better Approach: Separate Clones

For creating PRs, use **separate repository clones**:

✅ **Advantages**:
- Clean, isolated workspace for each repo
- Easy to fork, branch, and create PRs
- No submodule complexity
- Can delete and re-clone easily
- Standard git workflow

---

## Recommended Workflow

### Option 1: Use Setup Script (Recommended)

We've created a script to set up all repositories:

```bash
cd /home/intlc/projects/proxmox/explorer-monorepo
bash scripts/setup-pr-repositories.sh
```

**What it does**:
1. Creates a `pr-workspace` directory
2. Clones each repository (from your fork or original)
3. Sets up upstream remotes
4. Creates PR branches
5. Ready for you to make changes

### Option 2: Manual Setup

If you prefer manual control:

```bash
# Create workspace
mkdir -p ~/pr-workspace
cd ~/pr-workspace

# 1. ethereum-lists/chains
git clone https://github.com/YOUR_USERNAME/chains.git
cd chains
git remote add upstream https://github.com/ethereum-lists/chains.git
git checkout -b update-chainid-138-rpc-endpoints

# 2. Cross-Chain-Mirroring
cd ..
git clone https://github.com/YOUR_USERNAME/Cross-Chain-Mirroring.git
cd Cross-Chain-Mirroring
git remote add upstream https://github.com/Defi-Oracle-Meta-Blockchain/Cross-Chain-Mirroring.git
git checkout -b update-chainid-138-rpc-endpoints

# 3. app-ethereum
cd ..
git clone https://github.com/YOUR_USERNAME/app-ethereum.git
cd app-ethereum
git remote add upstream https://github.com/Defi-Oracle-Meta-Blockchain/app-ethereum.git
git checkout -b add-chainid-138-support
```

---

## Workflow Steps

### 1. Fork Repositories (First Time Only)

For each repository:
1. Go to repository on GitHub
2. Click "Fork" button
3. Fork to your account

**Repositories to fork**:
- https://github.com/ethereum-lists/chains
- https://github.com/Defi-Oracle-Meta-Blockchain/Cross-Chain-Mirroring
- https://github.com/Defi-Oracle-Meta-Blockchain/app-ethereum

### 2. Set Up Workspace

```bash
bash explorer-monorepo/scripts/setup-pr-repositories.sh
```

### 3. Make Changes

For each repository:

```bash
cd pr-workspace/<repo-name>

# Make your changes
# Edit files as needed

# Review changes
git status
git diff

# Commit
git add .
git commit -m "chore: update ChainID 138 RPC endpoints"
```

### 4. Push and Create PR

```bash
# Push to your fork
git push origin <branch-name>

# Then go to GitHub and create PR:
# 1. Go to your fork on GitHub
# 2. Click "Compare & pull request"
# 3. Fill in PR description
# 4. Submit PR
```

---

## Repository-Specific Instructions

### 1. ethereum-lists/chains (Priority 1)

**File to update**: `_data/chains/eip155-138/chain.json`

**Changes**:
```json
{
  "rpc": [
    "https://rpc-http-pub.d-bis.org",
    "https://rpc-http-prv.d-bis.org"
  ]
}
```

**Branch**: `update-chainid-138-rpc-endpoints`

### 2. Cross-Chain-Mirroring (Priority 2)

**Action**: Investigate and update RPC URLs

**Steps**:
```bash
cd pr-workspace/Cross-Chain-Mirroring
grep -r "rpc" . --include="*.json" --include="*.yaml" --include="*.env"
# Update any ChainID 138 RPC references
```

**Branch**: `update-chainid-138-rpc-endpoints`

### 3. app-ethereum (Priority 3)

**Action**: Check if ChainID 138 is supported, add if missing

**Steps**:
```bash
cd pr-workspace/app-ethereum
grep -r "138" . --include="*.c" --include="*.h" --include="*.json"
# If not found, add ChainID 138 configuration
```

**Branch**: `add-chainid-138-support`

---

## Directory Structure

After setup, you'll have:

```
pr-workspace/
├── chains/                          # ethereum-lists/chains
│   ├── _data/
│   │   └── chains/
│   │       └── eip155-138/
│   │           └── chain.json       # ← Update this
│   └── .git/
│
├── Cross-Chain-Mirroring/           # Cross-Chain-Mirroring
│   └── ...                          # ← Investigate and update
│
└── app-ethereum/                    # app-ethereum
    └── ...                          # ← Check/add ChainID 138
```

---

## Alternative: Git Submodules (Not Recommended)

If you really want submodules (not recommended for PRs):

```bash
cd /home/intlc/projects/proxmox/explorer-monorepo
git submodule add https://github.com/ethereum-lists/chains.git external/chains
git submodule add https://github.com/Defi-Oracle-Meta-Blockchain/Cross-Chain-Mirroring.git external/Cross-Chain-Mirroring
git submodule add https://github.com/Defi-Oracle-Meta-Blockchain/app-ethereum.git external/app-ethereum
```

**Why this is problematic**:
- Submodules point to specific commits
- Hard to work with latest code
- Complex workflow for PRs
- Need to fork separately anyway

---

## Summary

**Recommended Approach**:
1. ✅ **Fork repositories** on GitHub
2. ✅ **Use setup script** to clone and prepare
3. ✅ **Work in separate clones** (not submodules)
4. ✅ **Create PRs** from your forks

**Not Recommended**:
- ❌ Git submodules for PR work
- ❌ Working directly in main project

**Script Available**:
- `explorer-monorepo/scripts/setup-pr-repositories.sh`

---

**Last Updated**: 2025-12-24
**Status**: Ready to set up PR workspace