/public-repo-creation

name: public-repo-creation
description: Create production-ready public GitHub repositories with comprehensive documentation, automated setup, and quality assurance
tags: [github, documentation, open-source, repository, automation]
version: 1.0.0
origin: unknown
source_license: see upstream
language: en

Public Repository Creation

Create production-ready public GitHub repositories with comprehensive documentation, automated setup scripts, templates, and quality assurance processes.

When to Use

• Creating new open-source projects
• Publishing tools, libraries, or frameworks
• Building educational resources or examples
• Sharing integrations or automation scripts
• Any public-facing repository that needs professional polish

Core Components

1. Documentation Files (Required)

**README.md** (comprehensive):

• Clear title with emoji
• Badges (license, stars, build status)
• "What is This?" section
• Features (with subsections)
• Quick start (5-10 minutes)
• Manual setup (step-by-step)
• Example workflows
• Architecture diagram (ASCII or image)
• Folder structure
• Use cases
• Advanced features
• Performance metrics (if applicable)
• Contributing section
• License section
• Credits
• Support section

**LICENSE** (required):

• MIT recommended for maximum adoption
• Include copyright year and author

**CONTRIBUTING.md**:

• Quick start for contributors
• Code style guidelines
• Commit message format
• PR process
• Bug report template
• Feature request template

**TROUBLESHOOTING.md**:

• Installation issues (5+ solutions)
• Runtime issues (4+ solutions)
• Common errors with fixes
• Verification checklist

**CHECKLIST.md** (optional but recommended):

• Pre-installation checks
• Post-installation verification (10+ steps)
• Functional tests
• Success criteria

2. Automated Setup Script

**setup.sh** (or equivalent):

• Shebang (`#!/bin/bash`)
• Error handling (`set -e`)
• Prerequisites check
• Interactive prompts (with defaults)
• Conditional logic (skip if already installed)
• Fallback mechanisms
• Progress indicators
• Summary output
• Comments for each section

**Critical Patterns:**

# Prevent duplicate entries in config files
if ! grep -q "PATTERN" ~/.config 2>/dev/null; then
    echo "NEW_LINE" >> ~/.config
else
    sed -i "s|OLD_PATTERN|NEW_PATTERN|" ~/.config
fi

# Variable expansion in heredocs
cat > file.txt << EOF  # NO quotes for expansion
date: $(date +%Y-%m-%d)
EOF

# Fallback mechanism
if command_from_internet; then
    echo "✅ Installed from source"
else
    echo "⚠️  Source failed, using bundled copy..."
    cp -r bundled/ destination/
fi

3. Templates

**templates/** directory:

• Getting started template
• Daily/project note templates (if applicable)
• Configuration file templates
• .gitignore template

4. Examples

**EXAMPLE.md** or **examples/** directory:

• Real-world use case
• Step-by-step breakdown
• Code examples with syntax highlighting
• Expected output
• Benefits explanation

5. Quality Assurance

**Pre-commit checks:**

# Syntax validation
bash -n setup.sh

# Link validation
grep -o '\[.*\](.*\.md)' *.md | while read link; do
    file=$(echo "$link" | sed 's/.*(\\(.*\\))/\\1/')
    [ -f "$file" ] && echo "✅ $link" || echo "❌ Broken: $link"
done

# TODO/FIXME check
grep -ri "TODO\|FIXME\|XXX\|HACK" . --include="*.md" --include="*.sh"

# File permissions
ls -la setup.sh  # Should be executable

**AUDIT.md** (optional but professional):

• File inventory
• Quality checks performed
• Security analysis
• Performance metrics
• Recommendations

Workflow

Phase 1: Planning (5 minutes)

1. Define repository purpose (one sentence) 2. Identify target audience 3. List core features (3-5 main features) 4. Choose license (MIT recommended) 5. Plan folder structure

Phase 2: Core Setup (15 minutes)

1. Create GitHub repo (public) 2. Clone locally 3. Create README.md with title, description, badges 4. Create LICENSE file 5. Create .gitignore 6. Initial commit + push

Phase 3: Documentation (30 minutes)

1. Expand README.md:

• Features section
• Quick start
• Manual setup
• Examples
• Architecture

2. Create CONTRIBUTING.md 3. Create TROUBLESHOOTING.md 4. Create EXAMPLE.md

Phase 4: Automation (30 minutes)

1. Create setup.sh:

• Prerequisites check
• Interactive prompts
• Installation steps
• Configuration
• Summary output

2. Test setup.sh syntax: `bash -n setup.sh` 3. Make executable: `chmod +x setup.sh` 4. Test dry-run simulation

Phase 5: Templates & Examples (15 minutes)

1. Create templates/ directory 2. Add starter templates 3. Add example files 4. Document template usage in README

Phase 6: Quality Assurance (20 minutes)

1. Run syntax checks 2. Validate all links 3. Check file permissions 4. Test setup script (if possible) 5. Create CHECKLIST.md 6. Optional: Create AUDIT.md

Phase 7: Polish (10 minutes)

1. Add badges to README 2. Add architecture diagram 3. Add performance metrics (if applicable) 4. Add star history chart 5. Final commit + push

**Total Time:** ~2 hours for production-ready repo

Critical Pitfalls

1. Token/Config Duplication

**Problem:** Appending to config files without checking for duplicates.

**Wrong:**

echo "export TOKEN='xxx'" >> ~/.bashrc
# Run twice → duplicate entries!

**Right:**

if ! grep -q "export TOKEN=" ~/.bashrc 2>/dev/null; then
    echo "export TOKEN='xxx'" >> ~/.bashrc
else
    sed -i "s|export TOKEN=.*|export TOKEN='xxx'|" ~/.bashrc
fi

2. Heredoc Variable Expansion

**Problem:** Using single-quoted heredoc prevents variable expansion.

**Wrong:**

cat > file.txt << 'EOF'
date: $(date +%Y-%m-%d)
EOF
# Output: date: $(date +%Y-%m-%d)  ← LITERAL!

**Right:**

cat > file.txt << EOF  # No quotes!
date: $(date +%Y-%m-%d)
EOF
# Output: date: 2026-05-12  ← EXPANDED!

3. Hardcoded Paths

**Problem:** Hardcoding paths that may vary across systems.

**Consider:**

• Use `$HOME`