Merge origin/main: resolve conflicts in FORK_SETUP.md, README.md, frontend/package.json

Made-with: Cursor

docs/contribution/README.md

@@ -17,7 +17,9 @@ Complete guide to contributing to the ProxmoxVE project - from your first fork t
 
 ## 🚀 Quick Start
 
-### 60 Seconds to Contributing
+### 60 Seconds to Contributing (Development)
+
+When developing and testing **in your fork**:
 
 ```bash
 # 1. Fork on GitHub
@@ -27,8 +29,8 @@ Complete guide to contributing to the ProxmoxVE project - from your first fork t
 git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
 cd ProxmoxVE
 
-# 3. Auto-configure your fork
-bash docs/contribution/setup-fork.sh
+# 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
@@ -39,19 +41,73 @@ cat docs/ct/DETAILED_GUIDE.md   # For container scripts
 cat docs/install/DETAILED_GUIDE.md  # For install scripts
 
 # 6. Create your contribution
-cp ct/example.sh ct/myapp.sh
-cp install/example-install.sh install/myapp-install.sh
+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. Test and commit
-bash ct/myapp.sh
-git add ct/myapp.sh install/myapp-install.sh
-git commit -m "feat: add MyApp"
+# 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
 
-# 8. Create Pull Request on GitHub
+# 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:
+
+```bash
+# ✅ 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):**
+
+```bash
+# 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):**
+
+```bash
+# 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
@@ -61,13 +117,35 @@ git push origin feature/my-awesome-app
 When you clone your fork, run the setup script to automatically configure everything:
 
 ```bash
-bash docs/contribution/setup-fork.sh
+bash docs/contribution/setup-fork.sh --full
 ```
 
-This will:
-- Auto-detect your GitHub username
-- Update all documentation links to point to your fork
-- Create `.git-setup-info` with recommended git workflows
+**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](FORK_SETUP.md) for detailed instructions
 
@@ -80,11 +158,12 @@ If the script doesn't work, manually configure:
 git config user.name "Your Name"
 git config user.email "your.email@example.com"
 
-# Add upstream remote for syncing
+# 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)
 ```
 
 ---
@@ -97,9 +176,11 @@ All scripts and configurations must follow our coding standards to ensure consis
 
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - Essential coding standards and best practices
 - **[CODE-AUDIT.md](CODE-AUDIT.md)** - Code review checklist and audit procedures
+- **[GUIDE.md](GUIDE.md)** - Comprehensive contribution guide
+- **[HELPER_FUNCTIONS.md](HELPER_FUNCTIONS.md)** - Reference for all tools.func helper functions
 - **Container Scripts** - `/ct/` templates and guidelines
 - **Install Scripts** - `/install/` templates and guidelines
-- **JSON Configurations** - `/json/` structure and format
+- **JSON Configurations** - `frontend/public/json/` structure and format
 
 ### Quick Checklist
 
@@ -109,7 +190,7 @@ All scripts and configurations must follow our coding standards to ensure consis
 - ✅ 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
+- ✅ Test before submitting PR (via curl from your fork, not local bash)
 - ✅ Update documentation if needed
 
 ---
@@ -121,6 +202,7 @@ Before submitting a pull request, ensure your code passes our audit:
 **See**: [CODE-AUDIT.md](CODE-AUDIT.md) for complete audit checklist
 
 Key points:
+
 - Code consistency with existing scripts
 - Proper error handling
 - Correct variable naming
@@ -129,7 +211,172 @@ Key points:
 
 ---
 
-## 📚 Guides & Resources
+## 🍒 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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](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
+  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
 
@@ -145,6 +392,7 @@ Key points:
 ### Community Guides
 
 See [USER_SUBMITTED_GUIDES.md](USER_SUBMITTED_GUIDES.md) for excellent community-written guides:
+
 - Home Assistant installation and configuration
 - Frigate setup on Proxmox
 - Docker and Portainer installation
@@ -156,16 +404,24 @@ See [USER_SUBMITTED_GUIDES.md](USER_SUBMITTED_GUIDES.md) for excellent community
 Use these templates when creating new scripts:
 
 ```bash
-# Container script
-cp ct/example.sh ct/my-app.sh
+# Container script template
+cp docs/contribution/templates_ct/AppName.sh ct/my-app.sh
 
-# Installation script
-cp install/example-install.sh install/my-app-install.sh
+# Installation script template
+cp docs/contribution/templates_install/AppName-install.sh install/my-app-install.sh
 
-# JSON configuration (if needed)
-cp json/example.json json/my-app.json
+# 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
@@ -202,15 +458,18 @@ git push origin feature/my-feature
 ### Before Submitting PR
 
 1. **Sync with upstream**
+
    ```bash
    git fetch upstream
    git rebase upstream/main
    ```
 
-2. **Test your changes**
+2. **Test your changes** (via curl from your fork)
+
    ```bash
-   bash ct/my-app.sh
+   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**
@@ -244,23 +503,66 @@ Before opening a PR:
 
 ## ❓ FAQ
 
-### How do I test my changes?
+### ❌ Why can't I test with `bash ct/myapp.sh` locally?
+
+You might try:
 
 ```bash
-# For container scripts
-bash ct/my-app.sh
-
-# For install scripts (runs inside container)
-# The ct script will call it automatically
-
-# For advanced debugging
-VERBOSE=yes bash ct/my-app.sh
+# ❌ 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:
+
+```bash
+# ✅ 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:
+
+```bash
+# 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?
 
 ```bash
-# Sync with upstream
+# Sync with upstream main repository
 git fetch upstream
 git rebase upstream/main
 
@@ -272,17 +574,27 @@ git push -f origin your-branch
 
 ### How do I keep my fork updated?
 
-See "Keep Your Fork Updated" section above, or run:
+Two ways:
+
+**Option 1: Run setup script again**
 
 ```bash
-bash docs/contribution/setup-fork.sh
+bash docs/contribution/setup-fork.sh --full
+```
+
+**Option 2: Manual sync**
+
+```bash
+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
-- **Discord**: Community-scripts server
+- **GitHub Discussions**: For general questions and ideas
+- **Discord**: Community-scripts server for real-time chat
 
 ---
 
@@ -291,7 +603,7 @@ bash docs/contribution/setup-fork.sh
 ### For First-Time Contributors
 
 1. Read: [docs/README.md](../README.md) - Documentation overview
-2. Read: [docs/contribution/FORK_SETUP.md](FORK_SETUP.md) - Fork setup guide
+2. Read: [CONTRIBUTING.md](CONTRIBUTING.md) - Essential coding standards
 3. Choose your path:
    - Containers → [docs/ct/DETAILED_GUIDE.md](../ct/DETAILED_GUIDE.md)
    - Installation → [docs/install/DETAILED_GUIDE.md](../install/DETAILED_GUIDE.md)
@@ -301,22 +613,25 @@ bash docs/contribution/setup-fork.sh
 ### For Experienced Developers
 
 1. Review [CONTRIBUTING.md](CONTRIBUTING.md) - Coding standards
-2. Review [CODE-AUDIT.md](CODE-AUDIT.md) - Audit checklist
-3. Check templates in `/ct/` and `/install/`
-4. Submit PR with confidence
+2. Review [CODE_AUDIT.md](CODE_AUDIT.md) - Audit checklist
+3. Check templates in `/docs/contribution/templates_*/`
+4. Use AI assistants with [AI.md](AI.md) for code generation
+5. Submit PR with confidence
 
-### For Reviewers/Maintainers
+### For Using AI Assistants
 
-1. Use [CODE-AUDIT.md](CODE-AUDIT.md) as review guide
-2. Reference [docs/TECHNICAL_REFERENCE.md](../TECHNICAL_REFERENCE.md) for architecture
-3. Check [docs/EXIT_CODES.md](../EXIT_CODES.md) for error handling
+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`
+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
@@ -329,9 +644,9 @@ bash docs/contribution/setup-fork.sh
 
 ## 📞 Contact & Support
 
-- **GitHub**: https://github.com/community-scripts/ProxmoxVE
-- **Issues**: https://github.com/community-scripts/ProxmoxVE/issues
-- **Discussions**: https://github.com/community-scripts/ProxmoxVE/discussions
+- **GitHub**: [community-scripts/ProxmoxVE](https://github.com/community-scripts/ProxmoxVE)
+- **Issues**: [GitHub Issues](https://github.com/community-scripts/ProxmoxVE/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/community-scripts/ProxmoxVE/discussions)
 - **Discord**: [Join Server](https://discord.gg/UHrpNWGwkH)
 
 ---