ProxmoxVE/docs/contribution/FORK_SETUP.md

🍴 Fork Setup Guide

Just forked ProxmoxVE? Run this first!

Quick Start

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
cd ProxmoxVE

# Run setup script (auto-detects your username from git)
bash setup-fork.sh

That's it! ✅

---

What Does It Do?

The setup-fork.sh script automatically:

1. Detects your GitHub username from git config
2. Updates ALL hardcoded links to point to your fork:
   • Documentation links pointing to community-scripts/ProxmoxVE
   • Curl download URLs in scripts (e.g., curl ... github.com/community-scripts/ProxmoxVE/main/...)
3. Creates .git-setup-info with your configuration details
4. Backs up all modified files (*.backup for safety)

Why Updating Curl Links Matters

When you test scripts locally during development, the curl commands in your scripts need to pull from YOUR fork, not the upstream repository:

# During local testing, after setup-fork.sh runs:
bash ct/myapp.sh
# This will curl from: github.com/YOUR_USERNAME/ProxmoxVE/main
# NOT from: github.com/community-scripts/ProxmoxVE/main

# Once merged to upstream and published, users run:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"

---

Usage

Auto-Detect (Recommended)

bash setup-fork.sh

Automatically reads your GitHub username from git remote origin url

Specify Username

bash setup-fork.sh john

Updates links to github.com/john/ProxmoxVE

Custom Repository Name

bash setup-fork.sh john my-fork

Updates links to github.com/john/my-fork

---

What Gets Updated?

The script updates these documentation files:

• docs/CONTRIBUTION_GUIDE.md (4 links)
• docs/README.md (1 link)
• docs/INDEX.md (3 links)
• docs/EXIT_CODES.md (2 links)
• docs/DEFAULTS_SYSTEM_GUIDE.md (2 links)
• docs/api/README.md (1 link)
• docs/APP-ct.md (1 link)
• docs/APP-install.md (1 link)
• docs/alpine-install.func.md (2 links)
• docs/install.func.md (1 link)
• And code examples in documentation

---

After Setup

1. Review changes

   git diff docs/
   

2. Read git workflow tips

   cat .git-setup-info
   

3. Start contributing

   git checkout -b feature/my-app
   # Make your changes...
   git commit -m "feat: add my awesome app"
   

4. Follow the guide

   cat docs/CONTRIBUTION_GUIDE.md
   

---

Common Workflows

Keep Your Fork Updated

# Add upstream if you haven't already
git remote add upstream https://github.com/community-scripts/ProxmoxVE.git

# Get latest from upstream
git fetch upstream
git rebase upstream/main
git push origin main

Create a Feature Branch

git checkout -b feature/docker-improvements
# Make changes...
git push origin feature/docker-improvements
# Then create PR on GitHub

Sync Before Contributing

git fetch upstream
git rebase upstream/main
git push -f origin main  # Update your fork's main
git checkout -b feature/my-feature

---

Troubleshooting

"Git is not installed" or "not a git repository"

# Make sure you cloned the repo first
git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
cd ProxmoxVE
bash setup-fork.sh

"Could not auto-detect GitHub username"

# Your git origin URL isn't set up correctly
git remote -v
# Should show your fork URL, not community-scripts

# Fix it:
git remote set-url origin https://github.com/YOUR_USERNAME/ProxmoxVE.git
bash setup-fork.sh

"Permission denied"

# Make script executable
chmod +x setup-fork.sh
bash setup-fork.sh

Reverted Changes by Accident?

# Backups are created automatically
git checkout docs/*.backup
# Or just re-run setup-fork.sh

---

Next Steps

1. ✅ Run bash setup-fork.sh
2. 📖 Read docs/CONTRIBUTION_GUIDE.md
3. 🍴 Choose your contribution path:
   • Containers → docs/ct/README.md
   • Installation → docs/install/README.md
   • VMs → docs/vm/README.md
   • Tools → docs/tools/README.md
4. 💻 Create your feature branch and contribute!

---

Questions?

• Fork Setup Issues? → See Troubleshooting above
• How to Contribute? → docs/CONTRIBUTION_GUIDE.md
• Git Workflows? → cat .git-setup-info
• Project Structure? → docs/README.md

---

Happy Contributing! 🚀