comprehensive-public-repo-setup

# Comprehensive Public Repository Setup Pattern for creating production-ready public repositories that others can clone and use immediately. ## When to Use Creating a public repo that needs: - Comprehensive documentation - Automated setup (one-command install) - Bundled dependencies (no external failures) - Templates and examples - Troubleshooting guide - Installation verification ## Repository Structure ``` repo-name/ ├── README.md (10-15KB, comprehensive) ├── setup.sh (automated installation) ├── LICENSE (MIT recommended) ├── CONTRIBUTING.md ├── TROUBLESHOOTING.md (20+ solutions) ├── CHECKLIST.md (20+ verification steps) ├── EXAMPLE.md (real-world workflow) ├── templates/ │ ├── template1.md │ └── template2.md └── bundled-dependencies/ (if applicable) └── external-tool/ ``` ## README.md Structure Essential sections (in order): 1. **Title + Tagline** — with badges 2. **What is This?** — 2-3 sentence overview 3. **Features** — bullet points with emojis 4. **Quick Start** — 5-minute install 5. **Manual Setup** — step-by-step 6. **Workflow Example** — real-world use case 7. **Architecture** — ASCII diagram 8. **Use Cases** — when to use this 9. **Advanced Features** — optional capabilities 10. **Performance** — comparison if applicable 11. **Contributing** — link to CONTRIBUTING.md 12. **License** — MIT recommended 13. **Credits** — acknowledgments Example template: ```markdown # 🧠 Project Name **One-line description highlighting key benefits.** [](LICENSE) ## 🎯 What is This? Brief overview (2-3 sentences). ## ✨ Features - ⚡ **Feature 1** — description - 🧠 **Feature 2** — description ## 🚀 Quick Start \`\`\`bash git clone https://github.com/user/repo.git cd repo ./setup.sh \`\`\` ## 📖 Manual Setup Step-by-step instructions... ``` ## setup.sh Pattern Structure: ```bash #!/bin/bash set -e # Exit on error # Header echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "🎯 Project Setup" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" # 1. Check prerequisites echo "🔍 Checking prerequisites..." if ! command -v tool &> /dev/null; then echo "❌ Tool not found. Installing..." # Install command fi echo "✅ Prerequisites OK" echo "" # 2. Get user input (interactive) echo "📋 Configuration:" read -p "Username: " USERNAME read -sp "Token: " TOKEN echo "" echo "" # 3. Install dependencies with fallback echo "📦 Installing dependencies..." if git clone --depth 1 https://github.com/external/dep.git 2>/dev/null; then echo "✅ Installed from GitHub (latest)" else echo "⚠️ GitHub clone failed, using bundled copy..." SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cp -r "$SCRIPT_DIR/bundled-dep" "$INSTALL_DIR/" echo "✅ Installed from bundle" fi echo "" # 4. Configure echo "⚙️ Configuring..." # Configuration steps echo "✅ Configuration complete" echo "" # 5. Summary echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "✅ SETUP COMPLETE!" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" echo "📊 Summary:" echo " • Component 1: ✅" echo " • Component 2: ✅" echo "" echo "🎯 Next Steps:" echo " 1. Step one" echo " 2. Step two" echo "" ``` **Key principles:** - Use `set -e` (exit on error) - Check prerequisites before proceeding - Interactive prompts only for user-specific values - Fallback logic for external dependencies - Clear progress indicators (emojis + messages) - Summary at end with next steps ## Bundling External Dependencies **Problem:** External repos can disappear, change, or be rate-limited. **Solution:** Bundle critical dependencies with GitHub fallback. **Pattern:** ```bash # Try GitHub first (latest version) if git clone --depth 1 https://github.com/external/tool.git 2>/dev/null; then echo "✅ Installed from GitHub (latest)" else # Fallback: use bundled copy echo "⚠️ GitHub clone failed, using bundled copy..." SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" cp -r "$SCRIPT_DIR/bundled-tool" "$INSTALL_DIR/" echo "✅ Installed from bundle" fi ``` **When to bundle:** - Critical dependencies (setup fails without them) - Small size (<1MB preferred, <5MB acceptable) - Stable APIs (won't break with old version) - External repos with uncertain longevity **When NOT to bundle:** - Large dependencies (>10MB) - Frequently updated tools - OS packages (use package manager) ## TROUBLESHOOTING.md Structure Sections: 1. **Installation Issues** — errors during setup 2. **Runtime Issues** — problems after installation 3. **Sync/Network Issues** — connectivity problems 4. **Performance Issues** — slow operations 5. **Security Issues** — token/permission problems 6. **Verification Checklist** — confirm installation Format: ```markdown ### **"Error message"** **Problem:** Brief description. **Solution:** \`\`\`bash # Fix command \`\`\` ``` Aim for 20-30 solutions covering common issues. ## CHECKLIST.md Pattern Structure: 1. **Pre-installation** (5-10 checks) 2. **Post-installation** (10-15 verifications) 3. **Functional tests** (3-5 tests) 4. **Optional features** 5. **Success criteria** Format: ```markdown ### **1. Component Installed** \`\`\`bash command --version # Expected: version x.y.z \`\`\` - [ ] Command works - [ ] Version displayed ``` Aim for 20-30 total verification steps. ## Commit Strategy **Initial commit:** ```bash git add . git commit -m "Initial commit: README, setup script, examples, license" git push origin main ``` **Subsequent commits:** - One feature per commit - Descriptive messages - Group related changes **Good commit messages:** - "Add templates and troubleshooting guide" - "Bundle dependencies with GitHub fallback" - "Update documentation: add verification steps" ## Pitfalls ### ❌ Missing Bundled Dependencies **Problem:** Setup script clones from GitHub, but external repo is deleted/unavailable. **Solution:** Bundle critical dependencies in repo with fallback logic. **Real example:** User caught missing bundled dependency: "Woi lu lupa masukin obsidian skill?" ### ❌ Too Many Confirmation Prompts **Problem:** Script asks for confirmation at every step, slowing down installation. **User feedback:** "Lo langsung buat token aja, kerjain semuannya sendiri jngn kbanyakan nanya" **Solution:** - Only prompt for user-specific values (username, token) - Auto-proceed for standard operations - Use `--yes` flags where applicable - Show progress, don't ask permission ### ❌ Incomplete Documentation **Problem:** README doesn't cover edge cases, troubleshooting, or verification. **Solution:** Include: - TROUBLESHOOTING.md (20-30 solutions) - CHECKLIST.md (20-30 verification steps) - EXAMPLE.md (real-world workflow) ### ❌ Single Point of Failure **Problem:** Setup depends on external service being available. **Solution:** - Bundle dependencies - Provide fallback methods - Document manual alternatives ### ❌ No Verification Steps **Problem:** User doesn't know if installation succeeded. **Solution:** - CHECKLIST.md with verification commands - Setup script shows summary at end - Include functional tests ### ❌ Token Duplication in Bashrc **Problem:** Appending token to ~/.bashrc without checking if it already exists → multiple runs create duplicates. **Bad:** ```bash echo "export GH_TOKEN='$GITHUB_TOKEN'" >> ~/.bashrc # Run setup.sh 10x → 10 duplicate tokens! ``` **Good:** ```bash # Only add if not already present if ! grep -q "export GH_TOKEN=" ~/.bashrc 2>/dev/null; then echo "export GH_TOKEN='$GITHUB_TOKEN'" >> ~/.bashrc echo "✅ Token saved to ~/.bashrc" else # Update existing token sed -i "s|export GH_TOKEN=.*|export GH_TOKEN='$GITHUB_TOKEN'|" ~/.bashrc echo "✅ Token updated in ~/.bashrc" fi ``` **Real impact:** Found in mnemosyne-obsidian repo (commit `9cfbf55`). ### ❌ Date Not Expanding in Heredoc **Problem:** Single-quoted heredoc (`<< 'EOF'`) prevents variable expansion. **Bad:** ```bash cat > file.md << 'EOF' date: $(date +%Y-%m-%d) EOF # Output: date: $(date +%Y-%m-%d) ← LITERAL STRING! ``` **Good:** ```bash cat > file.md << EOF # Remove quotes! date: $(date +%Y-%m-%d) EOF # Output: date: 2026-05-12 ← ACTUAL DATE! ``` **Note:** Escape backticks in content: `` \`command\` `` **Real impact:** Found in mnemosyne-obsidian repo (commit `9cfbf55`). ## References - **[CRITICAL_BASH_PITFALLS.md](references/CRITICAL_BASH_PITFALLS.md)** — Common bash bugs in setup scripts (token duplication, heredoc quoting, path expansion, input validation) ## Real-World Example **Repo:** https://github.com/kevinnft/mnemosyne-obsidian **Structure:** - README.md (12KB) — comprehensive guide - setup.sh (6KB) — automated installation - EXAMPLE.md (3.7KB) — VPS cleanup workflow - TROUBLESHOOTING.md (5.4KB) — 30+ solutions - CHECKLIST.md (5.7KB) — 30+ verification steps - templates/ (4 files) — starter templates - obsidian-skills/ (340KB, 5 skills) — bundled dependency **Key features:** - ✅ One-command installation (`./setup.sh`) - ✅ Bundled obsidian-skills with GitHub fallback - ✅ Comprehensive documentation (7 files) - ✅ 30+ troubleshooting solutions - ✅ 30+ verification steps - ✅ Real-world example workflow - ✅ Works offline (after initial clone) **Installation flow:** ```bash git clone https://github.com/kevinnft/mnemosyne-obsidian.git cd mnemosyne-obsidian ./setup.sh # Enter username + token # Wait 5 minutes # Done! ``` ## Pre-Push Checklist Before pushing to GitHub: - [ ] README.md comprehensive (10+ sections) - [ ] setup.sh automated (5-minute install) - [ ] LICENSE included (MIT recommended) - [ ] CONTRIBUTING.md present - [ ] TROUBLESHOOTING.md with 20+ solutions - [ ] CHECKLIST.md with 20+ verification steps - [ ] EXAMPLE.md with real-world workflow - [ ] Templates directory (if applicable) - [ ] Critical dependencies bundled - [ ] Fallback logic for external deps - [ ] Clear commit messages - [ ] Repo description updated - [ ] All titles consistent ## Social Media Posts ### Character Limits **CRITICAL:** Social media platforms use **CHARACTER limits**, not word limits. **Common mistake:** "260 kata" (260 words) vs "260 karakter" (260 characters) **Platform limits:** - Twitter/X: 280 characters - LinkedIn: 3,000 characters (but 260 optimal for engagement) - Reddit title: 300 characters **Verification:** ```bash # Count characters (excluding newlines) cat post.txt | tr -d '\n' | wc -c ``` ### Post Structure (Twitter/X) **Format (under 260 chars):** ``` 🧠 [Hook: problem + solution] [Key feature 1] [Key feature 2] [Key feature 3] Built on @mention1 by @mention2 [Repo URL] #Tag1 #Tag2 ``` **Example (258 chars):** ``` 🧠 AI memory: 500x faster recall + rich notes + auto backup Mnemosyne + Obsidian + GitHub = best of all worlds ✅ 1-cmd setup ✅ Works offline ✅ MIT license Built on @nousresearch Hermes by @teknium https://github.com/user/repo #AI #Obsidian ``` ### Comment Thread (Detailed Explanation) **Structure (5 threads):** 1. **Problem** — What frustration does this solve? 2. **How It Works** — Technical overview (3 components) 3. **Real-World Example** — Concrete workflow (7 steps) 4. **Why Powerful** — Before/after comparison 5. **Installation + Features** — Quick start + feature list **Each thread:** 1-2 paragraphs, code blocks where helpful, end with hashtags. **Files to create:** - `SOCIAL_POST_SHORT.md` — Main post (under 260 chars) - `COMMENT_THREAD_EN.md` — English explanation (5 threads)