Update fork and release instructions in contribution docs

Replaced placeholder GitHub repo references with 'YourUsername/YourRepo' throughout documentation for clarity. Expanded explanations in FORK_SETUP.md and README.md to clarify the difference between development and production script execution, and emphasized the importance of cherry-picking only relevant files for PRs. Updated install script template examples to use the new repo placeholder.
2026-02-04 20:33:24 +01:00 · 2026-01-18 18:04:16 +01:00
parent 9671c9f391
commit e4ffc478fb
4 changed files with 110 additions and 33 deletions
--- a/docs/contribution/AI.md
+++ b/docs/contribution/AI.md
@@ -62,7 +62,7 @@ function update_script() {
    exit
  fi

-  if check_for_gh_release "appname" "owner/repo"; then
+  if check_for_gh_release "appname" "YourUsername/YourRepo"; then
    msg_info "Stopping Service"
    systemctl stop appname
    msg_ok "Stopped Service"
@@ -168,10 +168,10 @@ cleanup_lxc

 ### Release Management

-| Function                      | Description                         | Example                                            |
-| ----------------------------- | ----------------------------------- | -------------------------------------------------- |
-| `fetch_and_deploy_gh_release` | Fetches and installs GitHub Release | `fetch_and_deploy_gh_release "app" "owner/repo"`   |
-| `check_for_gh_release`        | Checks for new version              | `if check_for_gh_release "app" "owner/repo"; then` |
+| Function                      | Description                         | Example                                                       |
+| ----------------------------- | ----------------------------------- | ------------------------------------------------------------- |
+| `fetch_and_deploy_gh_release` | Fetches and installs GitHub Release | `fetch_and_deploy_gh_release "app" "YourUsername/YourRepo"`   |
+| `check_for_gh_release`        | Checks for new version              | `if check_for_gh_release "app" "YourUsername/YourRepo"; then` |

 **Modes for `fetch_and_deploy_gh_release`:**

@@ -259,13 +259,13 @@ cd /opt/myapp

 ```bash
 # ❌ WRONG - custom wget/curl logic
-RELEASE=$(curl -s https://api.github.com/repos/owner/repo/releases/latest | jq -r '.tag_name')
-wget https://github.com/owner/repo/archive/${RELEASE}.tar.gz
+RELEASE=$(curl -s https://api.github.com/repos/YourUsername/YourRepo/releases/latest | jq -r '.tag_name')
+wget https://github.com/YourUsername/YourRepo/archive/${RELEASE}.tar.gz
 tar -xzf ${RELEASE}.tar.gz
 mv repo-${RELEASE} /opt/myapp

 # ✅ CORRECT - use our function
-fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp"
+fetch_and_deploy_gh_release "myapp" "YourUsername/YourRepo" "tarball" "latest" "/opt/myapp"
 ```

 ### 3. Custom Version-Check Logic
@@ -273,13 +273,13 @@ fetch_and_deploy_gh_release "myapp" "owner/repo" "tarball" "latest" "/opt/myapp"
 ```bash
 # ❌ WRONG - custom version check
 CURRENT=$(cat /opt/myapp/version.txt)
-LATEST=$(curl -s https://api.github.com/repos/owner/repo/releases/latest | jq -r '.tag_name')
+LATEST=$(curl -s https://api.github.com/repos/YourUsername/YourRepo/releases/latest | jq -r '.tag_name')
 if [[ "$CURRENT" != "$LATEST" ]]; then
  # update...
 fi

 # ✅ CORRECT - use our function
-if check_for_gh_release "myapp" "owner/repo"; then
+if check_for_gh_release "myapp" "YourUsername/YourRepo"; then
  # update...
 fi
 ```
@@ -292,7 +292,7 @@ docker pull myapp/myapp:latest
 docker run -d --name myapp myapp/myapp:latest

 # ✅ CORRECT - Bare-Metal Installation
-fetch_and_deploy_gh_release "myapp" "owner/repo"
+fetch_and_deploy_gh_release "myapp" "YourUsername/YourRepo"
 npm install && npm run build
 ```

@@ -553,7 +553,7 @@ function update_script() {
  fi

  # 2. Check for update
-  if check_for_gh_release "appname" "owner/repo"; then
+  if check_for_gh_release "appname" "YourUsername/YourRepo"; then
    # 3. Stop service
    msg_info "Stopping Service"
    systemctl stop appname
@@ -826,11 +826,37 @@ Or no credentials:

 ---

+## 🍒 Important: Cherry-Picking Your Files for PR Submission
+
+⚠️ **CRITICAL**: When you submit your PR, you must use git cherry-pick to send ONLY your 3-4 files!
+
+Why? Because `setup-fork.sh` modifies 600+ files to update links. If you commit all changes, your PR will be impossible to merge.
+
+**See**: [README.md - Cherry-Pick Section](README.md#-cherry-pick-submitting-only-your-changes) for complete instructions on:
+
+- Creating a clean submission branch
+- Cherry-picking only your files (ct/myapp.sh, install/myapp-install.sh, frontend/public/json/myapp.json)
+- Verifying your PR has only 3 file changes (not 600+)
+
+**Quick reference**:
+
+```bash
+# Create clean branch from upstream
+git fetch upstream
+git checkout -b submit/myapp upstream/main
+
+# Cherry-pick your commit(s) or manually add your 3-4 files
+# Then push to your fork and create PR
+```
+
+---
+
 ## 📚 Further Documentation

 - [CONTRIBUTING.md](CONTRIBUTING.md) - General contribution guidelines
 - [GUIDE.md](GUIDE.md) - Detailed developer documentation
 - [HELPER_FUNCTIONS.md](HELPER_FUNCTIONS.md) - Complete tools.func reference
+- [README.md](README.md) - Cherry-pick guide and workflow instructions
 - [../TECHNICAL_REFERENCE.md](../TECHNICAL_REFERENCE.md) - Technical deep dive
 - [../EXIT_CODES.md](../EXIT_CODES.md) - Exit code reference
 - [templates_ct/](templates_ct/) - CT script templates
--- a/docs/contribution/FORK_SETUP.md
+++ b/docs/contribution/FORK_SETUP.md
@@ -26,20 +26,35 @@ The `setup-fork.sh` script automatically:
   - 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)
+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:
+Your scripts contain `curl` commands that download dependencies from GitHub (build.func, tools.func, etc.):

 ```bash
-# 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
+# First line of ct/myapp.sh
+source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
+```

-# Once merged to upstream and published, users run:
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"
+**WITHOUT setup-fork.sh:**
+- Script URLs still point to `community-scripts/ProxmoxVE/main`
+- When you test `bash ct/myapp.sh` locally, it downloads from the **upstream** repo, not your changes
+- Your modifications aren't actually being tested! ❌
+
+**AFTER setup-fork.sh:**
+- Script URLs are updated to `YourUsername/ProxmoxVE/main`
+- When you test `bash ct/myapp.sh` locally, it downloads from **your fork**
+- You're actually testing your changes! ✅
+
+```bash
+# Example: What setup-fork.sh changes
+
+# BEFORE (points to upstream):
+source <(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/misc/build.func)
+
+# AFTER (points to your fork):
+source <(curl -fsSL https://raw.githubusercontent.com/john/ProxmoxVE/main/misc/build.func)
 ```

 ---
@@ -47,21 +62,27 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
 ## Usage

 ### Auto-Detect (Recommended)
+
 ```bash
 bash setup-fork.sh
 ```
+
 Automatically reads your GitHub username from `git remote origin url`

 ### Specify Username
+
 ```bash
 bash setup-fork.sh john
 ```
+
 Updates links to `github.com/john/ProxmoxVE`

 ### Custom Repository Name
+
 ```bash
 bash setup-fork.sh john my-fork
 ```
+
 Updates links to `github.com/john/my-fork`

 ---
@@ -69,6 +90,7 @@ 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)
@@ -86,16 +108,19 @@ The script updates these documentation files:
 ## After Setup

 1. **Review changes**
+
   ```bash
   git diff docs/
   ```

 2. **Read git workflow tips**
+
   ```bash
   cat .git-setup-info
   ```

 3. **Start contributing**
+
   ```bash
   git checkout -b feature/my-app
   # Make your changes...
@@ -112,6 +137,7 @@ The script updates these documentation files:
 ## Common Workflows

 ### Keep Your Fork Updated
+
 ```bash
 # Add upstream if you haven't already
 git remote add upstream https://github.com/community-scripts/ProxmoxVE.git
@@ -123,6 +149,7 @@ git push origin main
 ```

 ### Create a Feature Branch
+
 ```bash
 git checkout -b feature/docker-improvements
 # Make changes...
@@ -131,6 +158,7 @@ git push origin feature/docker-improvements
 ```

 ### Sync Before Contributing
+
 ```bash
 git fetch upstream
 git rebase upstream/main
@@ -143,6 +171,7 @@ git checkout -b feature/my-feature
 ## Troubleshooting

 ### "Git is not installed" or "not a git repository"
+
 ```bash
 # Make sure you cloned the repo first
 git clone https://github.com/YOUR_USERNAME/ProxmoxVE.git
@@ -151,6 +180,7 @@ bash setup-fork.sh
 ```

 ### "Could not auto-detect GitHub username"
+
 ```bash
 # Your git origin URL isn't set up correctly
 git remote -v
@@ -162,6 +192,7 @@ bash setup-fork.sh
 ```

 ### "Permission denied"
+
 ```bash
 # Make script executable
 chmod +x setup-fork.sh
@@ -169,6 +200,7 @@ bash setup-fork.sh
 ```

 ### Reverted Changes by Accident?
+
 ```bash
 # Backups are created automatically
 git checkout docs/*.backup
--- a/docs/contribution/README.md
+++ b/docs/contribution/README.md
@@ -71,23 +71,38 @@ See the **Cherry-Pick: Submitting Only Your Changes** section below to learn how

 ### How Users Run Scripts (After Merged)

-Once your script is merged to the main repository, users run it like this:
+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)
+# ✅ Users run from GitHub (normal usage after PR merged)
 bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/myapp.sh)"

 # For installation on existing Proxmox hosts
 bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/install/myapp-install.sh)"
-
-# ❌ NOT from local files (that's only for development)
-bash ct/myapp.sh                # Only works during development in your fork
 ```

-**Why the difference?**
- **Development**: You test locally in your fork with `bash ct/myapp.sh`
- **Production**: Users always download from GitHub with `curl | bash`
- **setup-fork.sh**: Updates all your fork's links so curl pulls from YOUR fork during testing
+### Development vs. Production Execution
+
+**During Development (you, in your fork):**
+```bash
+bash ct/myapp.sh
+
+# The script's curl commands are updated by setup-fork.sh to pull from YOUR fork
+# This ensures you're testing your actual changes
+```
+
+**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**: `bash ct/myapp.sh` (local clone) → setup-fork.sh changes curl URLs to your fork
+- **Production**: `curl | bash` from upstream → curl URLs point to community-scripts repo

 ---

@@ -492,6 +507,7 @@ sh ct/myapp.sh
 ```

 **Why?**
+
 - Scripts use bash-specific features (arrays, process substitution, etc.)
 - Permissions might not be executable on Windows/WSL
 - Source files need proper `<(curl ...)` process substitution
@@ -533,11 +549,13 @@ git push -f origin your-branch
 Two ways:

 **Option 1: Run setup script again**
+
 ```bash
 bash docs/contribution/setup-fork.sh
 ```

 **Option 2: Manual sync**
+
 ```bash
 git fetch upstream
 git rebase upstream/main
@@ -575,6 +593,7 @@ git push -f origin main
 ### For Using AI Assistants

 See "Using AI Assistants" section above for:
+
 - How to structure prompts
 - What information to provide
 - How to validate AI output
--- a/docs/contribution/templates_install/AppName-install.sh
+++ b/docs/contribution/templates_install/AppName-install.sh
@@ -51,11 +51,11 @@ msg_ok "Installed Dependencies"
 #   "singlefile" - Single binary file
 #
 # Examples:
-#   fetch_and_deploy_gh_release "myapp" "owner/myapp" "tarball" "latest" "/opt/myapp"
-#   fetch_and_deploy_gh_release "myapp" "owner/myapp" "binary" "latest" "/tmp"
-#   fetch_and_deploy_gh_release "myapp" "owner/myapp" "prebuild" "latest" "/opt/myapp" "myapp-*.tar.gz"
+#   fetch_and_deploy_gh_release "myapp" "YourUsername/myapp" "tarball" "latest" "/opt/myapp"
+#   fetch_and_deploy_gh_release "myapp" "YourUsername/myapp" "binary" "latest" "/tmp"
+#   fetch_and_deploy_gh_release "myapp" "YourUsername/myapp" "prebuild" "latest" "/opt/myapp" "myapp-*.tar.gz"

-fetch_and_deploy_gh_release "[appname]" "[owner/repo]" "tarball" "latest" "/opt/[appname]"
+fetch_and_deploy_gh_release "[appname]" "YourUsername/YourRepo" "tarball" "latest" "/opt/[appname]"

 # =============================================================================
 # CONFIGURE APPLICATION