diff --git a/docs/contribution/AI.md b/docs/contribution/AI.md index d0f663e9e..fe0b241b9 100644 --- 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 diff --git a/docs/contribution/FORK_SETUP.md b/docs/contribution/FORK_SETUP.md index 6975155af..e2512356e 100644 --- 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 diff --git a/docs/contribution/README.md b/docs/contribution/README.md index c838c4cd7..639d9ed30 100644 --- 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 diff --git a/docs/contribution/templates_install/AppName-install.sh b/docs/contribution/templates_install/AppName-install.sh index 8b5dbf7c9..604e17ad7 100644 --- 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