public-repo-creation

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:
2. Features section
3. Quick start
4. Manual setup
5. Examples
6. Architecture
7. Create CONTRIBUTING.md
8. Create TROUBLESHOOTING.md
9. Create EXAMPLE.md

Phase 4: Automation (30 minutes)

1. Create setup.sh:
2. Prerequisites check
3. Interactive prompts
4. Installation steps
5. Configuration
6. Summary output
7. Test setup.sh syntax: bash -n setup.sh
8. Make executable: chmod +x setup.sh
9. 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 instead of /home/username
• Use $(dirname "${BASH_SOURCE[0]}") for script directory
• Make paths configurable via prompts or environment variables

4. Missing Fallback Mechanisms

Problem: Single point of failure (e.g., GitHub clone only).

Solution:

if git clone https://github.com/repo.git 2>/dev/null; then
    echo "✅ Cloned from GitHub"
else
    echo "⚠️  GitHub failed, using bundled copy..."
    cp -r bundled/ destination/
fi

5. Incomplete Documentation

Problem: Missing critical sections in README.

Must-have sections:

• What is This?
• Features
• Quick Start
• Installation
• Examples
• Troubleshooting
• Contributing
• License

6. No Quality Checks

Problem: Pushing without validation.

Always check:

• Syntax: bash -n setup.sh
• Links: Validate all internal links
• Permissions: Ensure setup.sh is executable
• TODOs: No TODO/FIXME in production

7. Character Count Confusion

Problem: Misunderstanding "260 kata" (words) vs "260 karakter" (characters).

Context: Indonesian "kata" = word, "karakter" = character.

Check:

# Word count
wc -w post.txt

# Character count (excluding newlines)
cat post.txt | tr -d '\n' | wc -c

Limits:

• Twitter/X: 280 characters (use 260 for safety)
• LinkedIn: 3,000 characters
• Reddit title: 300 characters
• Blog post: No strict limit (aim for 500-1000 words)

Always clarify with user: "260 words or 260 characters?"

8. Broken Internal Links

Problem: Referencing files that don't exist.

Check:

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

Title Consistency

When creating repos with multiple components (e.g., "Tool A + Tool B + Feature C"):

1. Update ALL titles to include all components:
2. README.md title
3. setup.sh comment header
4. EXAMPLE.md title
5. CONTRIBUTING.md title
6. GitHub repo description

1. Check consistency:

grep -h "^#.*Tool.*Feature" README.md EXAMPLE.md CONTRIBUTING.md setup.sh

Bundling Dependencies

When including third-party code (e.g., skills, libraries):

1. Bundle in repo (don't rely on external availability)
2. Remove nested .git directories
3. **Impl