ProxmoxVE/docs/contribution/README.md

🤝 Contributing to ProxmoxVE

Complete guide to contributing to the ProxmoxVE project - from your first fork to submitting your pull request.

---

📋 Table of Contents

• Quick Start
• Setting Up Your Fork
• Coding Standards
• Code Audit
• Guides & Resources
• FAQ

---

🚀 Quick Start

60 Seconds to Contributing (Development)

When developing and testing in your fork:

# 1. Fork on GitHub
# Visit: https://github.com/community-scripts/ProxmoxVE → Fork (top right)

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

# 3. Auto-configure your fork (IMPORTANT - updates all links!)
bash docs/contribution/setup-fork.sh --full

# 4. Create a feature branch
git checkout -b feature/my-awesome-app

# 5. Read the guides
cat docs/README.md              # Documentation overview
cat docs/ct/DETAILED_GUIDE.md   # For container scripts
cat docs/install/DETAILED_GUIDE.md  # For install scripts

# 6. Create your contribution
cp docs/contribution/templates_ct/AppName.sh ct/myapp.sh
cp docs/contribution/templates_install/AppName-install.sh install/myapp-install.sh
# ... edit files ...

# 7. Push to your fork and test via GitHub
git push origin feature/my-awesome-app
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
# ⏱️ GitHub may take 10-30 seconds to update files - be patient!

# 8. Create your JSON metadata file
cp docs/contribution/templates_json/AppName.json frontend/public/json/myapp.json
# Edit metadata: name, slug, categories, description, resources, etc.

# 9. No direct install-script test
# Install scripts are executed by the CT script inside the container

# 10. Commit ONLY your new files (see Cherry-Pick section below!)
git add ct/myapp.sh install/myapp-install.sh frontend/public/json/myapp.json
git commit -m "feat: add MyApp container and install scripts"
git push origin feature/my-awesome-app

# 11. Create Pull Request on GitHub

⚠️ IMPORTANT: After setup-fork.sh, many files are modified!

See the Cherry-Pick: Submitting Only Your Changes section below to learn how to push ONLY your 3-4 files instead of 600+ modified files!

How Users Run Scripts (After Merged)

Once your script is merged to the main repository, users download and run it from GitHub like this:

# ✅ Users run from GitHub (normal usage after PR merged)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"

# Install scripts are called by the CT script and are not run directly by users

Development vs. Production Execution

During Development (you, in your fork):

# You MUST test via curl from your GitHub fork (not local files!)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"

# The script's curl commands are updated by setup-fork.sh to point to YOUR fork
# This ensures you're testing your actual changes
# ⏱️ Wait 10-30 seconds after pushing - GitHub updates slowly

After Merge (users, from GitHub):

# Users download the script from upstream via curl
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"

# The script's curl commands now point back to upstream (community-scripts)
# This is the stable, tested version

Summary:

• Development: Push to fork, test via curl → setup-fork.sh changes curl URLs to your fork
• Production: curl | bash from upstream → curl URLs point to community-scripts repo

---

🍴 Setting Up Your Fork

Automatic Setup (Recommended)

When you clone your fork, run the setup script to automatically configure everything:

bash docs/contribution/setup-fork.sh --full

What it does:

• Auto-detects your GitHub username from git config
• Auto-detects your fork repository name
• Updates ALL hardcoded links to point to your fork instead of the main repo (--full)
• Creates .git-setup-info with your configuration
• Allows you to develop and test independently in your fork

Why this matters:

Without running this script, all links in your fork will still point to the upstream repository (community-scripts). This is a problem when testing because:

• Installation links will pull from upstream, not your fork
• Updates will target the wrong repository
• Your contributions won't be properly tested

After running setup-fork.sh:

Your fork is fully configured and ready to develop. You can:

• Push changes to your fork
• Test via curl: bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
• All links will reference your fork for development
• ⏱️ Wait 10-30 seconds after pushing - GitHub takes time to update
• Commit and push with confidence
• Create a PR to merge into upstream

See: FORK_SETUP.md for detailed instructions

Manual Setup

If the script doesn't work, manually configure:

# Set git user
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Add upstream remote for syncing with main repo
git remote add upstream https://github.com/community-scripts/ProxmoxVE.git

# Verify remotes
git remote -v
# Should show: origin (your fork) and upstream (main repo)

---

📖 Coding Standards

All scripts and configurations must follow our coding standards to ensure consistency and quality.

Available Guides

• CONTRIBUTING.md - Essential coding standards and best practices
• CODE_AUDIT.md - Code review checklist and audit procedures
• GUIDE.md - Comprehensive contribution guide
• HELPER_FUNCTIONS.md - Reference for all tools.func helper functions
• Container Scripts - /ct/ templates and guidelines
• Install Scripts - /install/ templates and guidelines
• JSON Configurations - frontend/public/json/ structure and format

Quick Checklist

• ✅ Use /ct/example.sh as template for container scripts
• ✅ Use /install/example-install.sh as template for install scripts
• ✅ Follow naming conventions: appname.sh and appname-install.sh
• ✅ Include proper shebang: #!/usr/bin/env bash
• ✅ Add copyright header with author
• ✅ Handle errors properly with msg_error, msg_ok, etc.
• ✅ Test before submitting PR (via curl from your fork, not local bash)
• ✅ Update documentation if needed

---

🔍 Code Audit

Before submitting a pull request, ensure your code passes our audit:

See: CODE_AUDIT.md for complete audit checklist

Key points:

• Code consistency with existing scripts
• Proper error handling
• Correct variable naming
• Adequate comments and documentation
• Security best practices

---

🍒 Cherry-Pick: Submitting Only Your Changes

Problem: setup-fork.sh modifies 600+ files to update links. You don't want to submit all of those changes - only your new 3-4 files!

Solution: Use git cherry-pick to select only YOUR files.

Step-by-Step Cherry-Pick Guide

1. Check what changed

# See all modified files
git status

# Verify your files are there
git status | grep -E "ct/myapp|install/myapp|json/myapp"

2. Create a clean feature branch for submission

# Go back to upstream main (clean slate)
git fetch upstream
git checkout -b submit/myapp upstream/main

# Don't use your modified main branch!

3. Cherry-pick ONLY your files

Cherry-picking extracts specific changes from commits:

# Option A: Cherry-pick commits that added your files
# (if you committed your files separately)
git cherry-pick <commit-hash-of-your-files>

# Option B: Manually copy and commit only your files
# From your work branch, get the file contents
git show feature/my-awesome-app:ct/myapp.sh > /tmp/myapp.sh
git show feature/my-awesome-app:install/myapp-install.sh > /tmp/myapp-install.sh
git show feature/my-awesome-app:frontend/public/json/myapp.json > /tmp/myapp.json

# Add them to the clean branch
cp /tmp/myapp.sh ct/myapp.sh
cp /tmp/myapp-install.sh install/myapp-install.sh
cp /tmp/myapp.json frontend/public/json/myapp.json

# Commit
git add ct/myapp.sh install/myapp-install.sh frontend/public/json/myapp.json
git commit -m "feat: add MyApp"

4. Verify only your files are in the PR

# Check git diff against upstream
git diff upstream/main --name-only
# Should show ONLY:
#   ct/myapp.sh
#   install/myapp-install.sh
#   frontend/public/json/myapp.json

5. Push and create PR

# Push your clean submission branch
git push origin submit/myapp

# Create PR on GitHub from: submit/myapp → main

Why This Matters

• ✅ Clean PR with only your changes
• ✅ Easier for maintainers to review
• ✅ Faster merge without conflicts
• ❌ Without cherry-pick: PR has 600+ file changes (won't merge!)

If You Made a Mistake

# Delete the messy branch
git branch -D submit/myapp

# Go back to clean branch
git checkout -b submit/myapp upstream/main

# Try cherry-picking again

---

If you're using Visual Studio Code with an AI assistant, you can leverage our detailed guidelines to generate high-quality contributions automatically.

How to Use AI Assistance

1. Open the AI Guidelines

   docs/contribution/AI.md
   

   This file contains all requirements, patterns, and examples for writing proper scripts.

2. Prepare Your Information

   Before asking the AI to generate code, gather:

   • Repository URL: e.g., https://github.com/owner/myapp
   • Dockerfile/Script: Paste the app's installation instructions (if available)
   • Dependencies: What packages does it need? (Node, Python, Java, PostgreSQL, etc.)
   • Ports: What port does it listen on? (e.g., 3000, 8080, 5000)
   • Configuration: Any environment variables or config files?

3. Tell the AI Assistant

   Share with the AI:

   • The repository URL
   • The Dockerfile or install instructions
   • Link to docs/contribution/AI.md with instructions to follow

   Example prompt:

   I want to contribute a container script for MyApp to ProxmoxVE.
   Repository: https://github.com/owner/myapp
   
   Here's the Dockerfile:
   [paste Dockerfile content]
   
   Please follow the guidelines in docs/contribution/AI.md to create:
   1. ct/myapp.sh (container script)
   2. install/myapp-install.sh (installation script)
   3. frontend/public/json/myapp.json (metadata)
   

4. AI Will Generate

   The AI will produce scripts that:

   • Follow all ProxmoxVE patterns and conventions
   • Use helper functions from tools.func correctly
   • Include proper error handling and messages
   • Have correct update mechanisms
   • Are ready to submit as a PR

Key Points for AI Assistants

• Templates Location: docs/contribution/templates_ct/AppName.sh, templates_install/, templates_json/
• Guidelines: Must follow docs/contribution/AI.md exactly
• Helper Functions: Use only functions from misc/tools.func - never write custom ones
• Testing: Always test before submission via curl from your fork

  bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"
  # Wait 10-30 seconds after pushing changes
  

• No Docker: Container scripts must be bare-metal, not Docker-based

Benefits

• Speed: AI generates boilerplate in seconds
• Consistency: Follows same patterns as 200+ existing scripts
• Quality: Less bugs and more maintainable code
• Learning: See how your app should be structured

---

Documentation

• docs/README.md - Main documentation hub
• docs/ct/README.md - Container scripts overview
• docs/install/README.md - Installation scripts overview
• docs/ct/DETAILED_GUIDE.md - Complete ct/ script reference
• docs/install/DETAILED_GUIDE.md - Complete install/ script reference
• docs/TECHNICAL_REFERENCE.md - Architecture deep-dive
• docs/EXIT_CODES.md - Exit codes reference
• docs/DEV_MODE.md - Debugging guide

Community Guides

See USER_SUBMITTED_GUIDES.md for excellent community-written guides:

• Home Assistant installation and configuration
• Frigate setup on Proxmox
• Docker and Portainer installation
• Database setup and optimization
• And many more!

Templates

Use these templates when creating new scripts:

# Container script template
cp docs/contribution/templates_ct/AppName.sh ct/my-app.sh

# Installation script template
cp docs/contribution/templates_install/AppName-install.sh install/my-app-install.sh

# JSON configuration template
cp docs/contribution/templates_json/AppName.json frontend/public/json/my-app.json

Template Features:

• Updated to match current codebase patterns
• Includes all available helper functions from tools.func
• Examples for Node.js, Python, PHP, Go applications
• Database setup examples (MariaDB, PostgreSQL)
• Proper service creation and cleanup

---

🔄 Git Workflow

Keep Your Fork Updated

# Fetch latest from upstream
git fetch upstream

# Rebase your work on latest main
git rebase upstream/main

# Push to your fork
git push -f origin main

Create Feature Branch

# Create and switch to new branch
git checkout -b feature/my-feature

# Make changes...
git add .
git commit -m "feat: description of changes"

# Push to your fork
git push origin feature/my-feature

# Create Pull Request on GitHub

Before Submitting PR

1. Sync with upstream

   git fetch upstream
   git rebase upstream/main
   

2. Test your changes (via curl from your fork)

   bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"
   # Follow prompts and test the container
   # ⏱️ Wait 10-30 seconds after pushing - GitHub takes time to update
   

3. Check code standards

   • Follows template structure
   • Proper error handling
   • Documentation updated (if needed)
   • No hardcoded values
   • Version tracking implemented

4. Push final changes

   git push origin feature/my-feature
   

---

📋 Pull Request Checklist

Before opening a PR:

• Code follows coding standards (see CONTRIBUTING.md)
• All templates used correctly
• Tested on Proxmox VE
• Error handling implemented
• Documentation updated (if applicable)
• No merge conflicts
• Synced with upstream/main
• Clear PR title and description

---

❓ FAQ

❌ Why can't I test with bash ct/myapp.sh locally?

You might try:

# ❌ WRONG - This won't test your actual changes!
bash ct/myapp.sh
./ct/myapp.sh
sh ct/myapp.sh

Why this fails:

• bash ct/myapp.sh uses the LOCAL clone file
• The LOCAL file doesn't execute the curl commands - it's already on disk
• The curl URLs INSIDE the script are modified by setup-fork.sh, but they're not executed
• So you can't verify if your curl URLs actually work
• Users will get the curl URL version (which may be broken)

Solution: Always test via curl from GitHub:

# ✅ CORRECT - Tests the actual GitHub URLs
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/myapp.sh)"

❓ How do I test my changes?

You cannot test locally with bash ct/myapp.sh from your cloned directory!

You must push to GitHub and test via curl from your fork:

# 1. Push your changes to your fork
git push origin feature/my-awesome-app

# 2. Test via curl (this loads the script from GitHub, not local files)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"

# 3. For verbose/debug output, pass environment variables
VERBOSE=yes bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"
DEV_MODE_LOGS=true bash -c "$(curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/ProxmoxVE/main/ct/my-app.sh)"

Why?

• Local bash ct/myapp.sh uses local files from your clone
• But the script's INTERNAL curl commands have been modified by setup-fork.sh to point to your fork
• This discrepancy means you're not actually testing the curl URLs
• Testing via curl ensures the script downloads from YOUR fork GitHub URLs
• ⏱️ Important: GitHub takes 10-30 seconds to recognize newly pushed files. Wait before testing!

What if local bash worked?

You'd be testing local files only, not the actual GitHub URLs that users will download. This means broken curl links wouldn't be caught during testing.

What if my PR has conflicts?

# Sync with upstream main repository
git fetch upstream
git rebase upstream/main

# Resolve conflicts in your editor
git add .
git rebase --continue
git push -f origin your-branch

How do I keep my fork updated?

Two ways:

Option 1: Run setup script again

bash docs/contribution/setup-fork.sh --full

Option 2: Manual sync

git fetch upstream
git rebase upstream/main
git push -f origin main

Where do I ask questions?

• GitHub Issues: For bugs and feature requests
• GitHub Discussions: For general questions and ideas
• Discord: Community-scripts server for real-time chat

---

🎓 Learning Resources

For First-Time Contributors

1. Read: docs/README.md - Documentation overview
2. Read: CONTRIBUTING.md - Essential coding standards
3. Choose your path:
   • Containers → docs/ct/DETAILED_GUIDE.md
   • Installation → docs/install/DETAILED_GUIDE.md
4. Study existing scripts in same category
5. Create your contribution

For Experienced Developers

1. Review CONTRIBUTING.md - Coding standards
2. Review CODE_AUDIT.md - Audit checklist
3. Check templates in /docs/contribution/templates_*/
4. Use AI assistants with AI.md for code generation
5. Submit PR with confidence

For Using AI Assistants

See "Using AI Assistants" section above for:

• How to structure prompts
• What information to provide
• How to validate AI output

---

🚀 Ready to Contribute?

1. Fork the repository
2. Clone your fork and setup with bash docs/contribution/setup-fork.sh --full
3. Choose your contribution type (container, installation, tools, etc.)
4. Read the appropriate detailed guide
5. Create your feature branch
6. Develop and test your changes
7. Commit with clear messages
8. Push to your fork
9. Create Pull Request

---

📞 Contact & Support

• GitHub: community-scripts/ProxmoxVE
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join Server

---

Thank you for contributing to ProxmoxVE! 🙏

Your efforts help make Proxmox VE automation accessible to everyone. Happy coding! 🚀