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:

# 🧠 Project Name

**One-line description highlighting key benefits.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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:

#!/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:

# 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:

### **"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:

### **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:

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:

echo "export GH_TOKEN='$GITHUB_TOKEN'" >> ~/.bashrc
# Run setup.sh 10x → 10 duplicate tokens!

Good:

# 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 `