github-repository-architect

1. Repository Foundation

• Initialization: Git configuration, .gitignore, license selection, README structure
• Branch Strategy: Main/develop branches, protection rules, merge policies
• Access Control: Team permissions, CODEOWNERS, branch protection
• Repository Settings: Features enablement, security policies, merge options
• Topics & Metadata: Discoverability optimization, GitHub search ranking

2. Community Health Files

• README.md: Project overview, quick start, badges, contributing links
• LICENSE: License selection and proper copyright attribution
• CODE_OF_CONDUCT.md: Community standards and enforcement
• CONTRIBUTING.md: Contribution guidelines and development workflow
• SECURITY.md: Security policy and vulnerability reporting
• CHANGELOG.md: Version history following Keep a Changelog format
• CITATION.cff: Academic citation support (Citation File Format)

3. Issue & PR Templates

• Issue Templates: Bug reports, feature requests, documentation improvements
• Pull Request Template: PR description structure, checklist, review guidelines
• Discussion Templates: Q&A, ideas, announcements (if Discussions enabled)
• Custom Forms: GitHub issue forms with type validation
• Auto-labeling: Automatic label application based on issue type

4. CI/CD Automation

• GitHub Actions: Automated testing, linting, building, deployment
• Quality Gates: Code coverage, security scanning, dependency audits
• Release Automation: Semantic versioning, changelog generation, asset publishing
• Documentation Deployment: GitHub Pages auto-deployment on push
• Dependency Management: Dependabot, automated PR creation for updates

5. Documentation Site

• GitHub Pages: Static site deployment (Jekyll, Docsify, MkDocs, or custom)
• Site Structure: Hierarchical navigation, search functionality
• Custom Domain: DNS configuration and HTTPS setup
• SEO Optimization: Meta tags, sitemaps, structured data
• Mobile Responsive: Cross-device compatibility testing

Phase 1: Repository Initialization (30 min)

Step 1: Local Repository Setup

```bash

# Initialize git repository

git init

git branch -M main

# Create essential files

touch README.md LICENSE .gitignore

# First commit

git add .

git commit -m "chore: initialize repository"

```

Step 2: GitHub Repository Creation

```bash

# Create on GitHub (via gh CLI)

gh repo create OWNER/REPO --public --source=. --remote=origin

# Or use GitHub web interface for more options

```

Step 3: Repository Settings

• Enable Issues, Discussions, Projects (as needed)
• Disable Wiki (if using external docs)
• Set default branch to main
• Configure merge options (squash, rebase, merge commits)
• Enable "Automatically delete head branches"

Phase 2: Community Health Files (45 min)

README.md Template:

```markdown

# Project Name

[](https://github.com/OWNER/REPO/releases)

[](LICENSE)

[](https://github.com/OWNER/REPO/actions)

One-sentence project description

• Feature 1
• Feature 2
• Feature 3

\\\`bash

# Installation

npm install @org/package

# Usage

import { function } from '@org/package'

\\\`

Full documentation: [https://owner.github.io/repo](https://owner.github.io/repo)

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

[MIT License](LICENSE) - see LICENSE file for details.

```

LICENSE Selection Guide:

• MIT: Permissive, simple, widely used (recommended for most projects)
• Apache 2.0: Patent grant protection, enterprise-friendly
• GPL v3: Copyleft, derivatives must be open-source
• CC BY-NC-ND 4.0: Creative Commons for non-code content (documentation, frameworks)
• Proprietary: Custom license for closed-source with limited distribution

CODE_OF_CONDUCT.md:

Use Contributor Covenant (industry standard):

```bash

# Via gh CLI

gh repo create-conduct

# Or download from https://www.contributor-covenant.org/

```

CONTRIBUTING.md Structure:

1. Getting Started (development environment setup)
2. Development Workflow (branch naming, commit messages)
3. Pull Request Process (review criteria, testing requirements)
4. Code Style Guidelines (linting, formatting)
5. Testing Requirements (coverage thresholds, test types)
6. Documentation Standards (inline comments, external docs)

SECURITY.md:

```markdown

# Security Policy

| Version | Supported |

| ------- | ------------------ |

| 1.x | :white_check_mark: |

| < 1.0 | :x: |

DO NOT open a public issue for security vulnerabilities.

Email: security@example.com

Expected response time: 48 hours

```

CHANGELOG.md:

Follow [Keep a Changelog](https://keepachangelog.com/) format:

```markdown

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),

and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Added

• Initial release
• Feature X
• Feature Y

Changed

• Updated dependency Z

Fixed

• Bug fix for issue #123

```

CITATION.cff:

```yaml

cff-version: 1.2.0

title: "Project Name"

message: "If you use this software, please cite it as below."

type: software

authors:

- family-names: Last

given-names: First

email: author@example.com

orcid: "https://orcid.org/0000-0000-0000-0000"

repository-code: "https://github.com/OWNER/REPO"

url: "https://owner.github.io/repo"

license: MIT

version: 1.0.0

date-released: 2025-11-01

```

Phase 3: Issue & PR Templates (30 min)

Directory Structure:

```

.github/

├── ISSUE_TEMPLATE/

│ ├── bug_report.md

│ ├── feature_request.md

│ └── documentation.md

├── PULL_REQUEST_TEMPLATE.md

└── CODEOWNERS

```

Bug Report Template (.github/ISSUE_TEMPLATE/bug_report.md):

```markdown

---

name: Bug Report

about: Report a bug or unexpected behavior

title: "[BUG] "

labels: bug

assignees: ''

---

A clear description of the bug.

1. Step 1
2. Step 2
3. See error

What should happen.

What actually happens.

• OS: [e.g., macOS 14.0]
• Version: [e.g., 1.0.0]
• Node: [e.g., 20.10.0]

Screenshots, logs, or other context.

```

Feature Request Template:

```markdown

---

name: Feature Request

about: Suggest a new feature or enhancement

title: "[FEATURE] "

labels: enhancement

assignees: ''

---

What problem does this solve?

How should it work?

Other approaches you've thought about.

Any other relevant information.

```

Pull Request Template (.github/PULL_REQUEST_TEMPLATE.md):

```markdown

Brief description of changes.

• [ ] Bug fix (non-breaking change fixing an issue)
• [ ] New feature (non-breaking change adding functionality)
• [ ] Breaking change (fix or feature causing existing functionality to break)
• [ ] Documentation update

• [ ] Unit tests pass
• [ ] Integration tests pass
• [ ] Manual testing completed

• [ ] Code follows style guidelines
• [ ] Self-review completed
• [ ] Comments added for complex code
• [ ] Documentation updated
• [ ] No new warnings generated
• [ ] Tests added covering changes
• [ ] All tests passing
• [ ] CHANGELOG.md updated

Closes #(issue number)

```

CODEOWNERS (.github/CODEOWNERS):

```

# Global owners

• @organization/maintainers

# Specific paths

/docs/ @organization/docs-team

/src/ @organization/core-team

/.github/ @organization/devops-team

/tests/ @organization/qa-team

```

Phase 4: CI/CD Workflows (60 min)

Lint Workflow (.github/workflows/lint.yml):

```yaml

name: Lint

on:

push:

branches: [ main, develop ]

pull_request:

branches: [ main, develop ]

jobs:

lint:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Setup Node.js

uses: actions/setup-node@v4

with:

node-version: '20'

cache: 'npm'

- name: Install dependencies

run: npm ci

- name: Run ESLint

run: npm run lint

- name: Run Prettier

run: npm run format:check

```

Test Workflow (.github/workflows/test.yml):

```yaml

name: Test

on:

push:

branches: [ main, develop ]

pull_request:

branches: [ main, develop ]

jobs:

test:

runs-on: ${{ matrix.os }}

strategy:

matrix:

os: [ubuntu-latest, windows-latest, macos-latest]

node-version: [18.x, 20.x]

steps:

- uses: actions/checkout@v4

- name: Setup Node.js ${{ matrix.node-version }}

uses: actions/setup-node@v4

with:

node-version: ${{ matrix.node-version }}

cache: 'npm'

- name: Install dependencies

run: npm ci

- name: Run tests

run: npm test

- name: Upload coverage

uses: codecov/codecov-action@v3

with:

files: ./coverage/lcov.info

```

Release Workflow (.github/workflows/release.yml):

```yaml

name: Release

on:

push:

tags:

- 'v*'

jobs:

release:

runs-on: ubuntu-latest

permissions:

contents: write

steps:

- uses: actions/checkout@v4

- name: Create Release

uses: actions/create-release@v1

env:

GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

with:

tag_name: ${{ github.ref }}

release_name: Release ${{ github.ref }}

draft: false

prerelease: false

```

GitHub Pages Deploy (.github/workflows/pages.yml):

```yaml

name: Deploy to GitHub Pages

on:

push:

branches: [ main ]

workflow_dispatch:

permissions:

contents: read

pages: write

id-token: write

jobs:

build:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Setup Pages

uses: actions/configure-pages@v4

- name: Build site

run: |

# Build commands here

npm run build:docs

- name: Upload artifact

uses: actions/upload-pages-artifact@v3

with:

path: ./docs

deploy:

environment:

name: github-pages

url: ${{ steps.deployment.outputs.page_url }}

runs-on: ubuntu-latest

needs: build

steps:

- name: Deploy to GitHub Pages

id: deployment

uses: actions/deploy-pages@v4

```

Phase 5: Documentation Site (60 min)

Option 1: Docsify (Recommended for simplicity)

1. Create docs/ directory structure:

```

docs/

├── index.html (Docsify config)

├── README.md (Home page)

├── _sidebar.md (Navigation)

├── guide/

│ ├── getting-started.md

│ └── advanced.md

└── reference/

├── api.md

└── cli.md

```

1. docs/index.html:

```html

```

1. docs/_sidebar.md:

```markdown

• [Home](/)
• [Getting Started](guide/getting-started.md)
• [API Reference](reference/api.md)

```

Option 2: Jekyll (GitHub Pages default)

1. Create _config.yml:

```yaml

title: Project Documentation

description: Project description

theme: jekyll-theme-cayman

markdown: kramdown

```

1. Enable GitHub Pages in repository settings
2. Select source: main branch, /docs folder

Option 3: MkDocs (Python-based, feature-rich)

1. Install: pip install mkdocs mkdocs-material
2. Initialize: mkdocs new .
3. Configure mkdocs.yml
4. Build: mkdocs build
5. Deploy: mkdocs gh-deploy

Phase 6: Badges & Metadata (15 min)

Essential Badges:

```markdown

[](https://github.com/OWNER/REPO/releases)

[](LICENSE)

[](https://github.com/OWNER/REPO/actions)

[](https://codecov.io/gh/OWNER/REPO)

[](https://www.npmjs.com/package/@org/package)

```

Repository Topics:

• Maximum 20 topics
• Use lowercase, hyphens for spaces
• Include: language, framework, use-case, industry
• Example: typescript, api, mental-models, cognitive-framework

About Section:

• Concise description (160 chars max)
• Include primary use case
• Add website URL if applicable
• Select appropriate topics

Repository Health ✅

• [ ] README with badges, quick start, and documentation links
• [ ] LICENSE file present and appropriate
• [ ] CODE_OF_CONDUCT.md following Contributor Covenant
• [ ] CONTRIBUTING.md with clear guidelines
• [ ] SECURITY.md with vulnerability reporting process
• [ ] CHANGELOG.md following Keep a Changelog format
• [ ] .gitignore appropriate for project type

Automation ✅

• [ ] CI workflow testing on push/PR
• [ ] Linting workflow enforcing code style
• [ ] Security scanning (Dependabot, CodeQL)
• [ ] Automated releases on version tags
• [ ] Documentation deployment on main branch push

Templates ✅

• [ ] Bug report template
• [ ] Feature request template
• [ ] Pull request template with checklist
• [ ] CODEOWNERS file for automatic review assignment

Documentation ✅

• [ ] GitHub Pages enabled and deploying
• [ ] Navigation structure clear and hierarchical
• [ ] Search functionality working
• [ ] Mobile-responsive design
• [ ] All links functional

Metadata ✅

• [ ] Repository description set
• [ ] Topics configured (10-20 relevant tags)
• [ ] Website URL added (if applicable)
• [ ] Social preview image (1280x640px)

Branch Protection Rules

```

Settings → Branches → Add rule

Branch name pattern: main

Protection settings:

✅ Require pull request before merging

✅ Require approvals (1-2)

✅ Dismiss stale reviews

✅ Require status checks to pass

✅ Require branches to be up to date

✅ Require conversation resolution before merging

✅ Require signed commits (optional, high security)

✅ Include administrators (recommended)

```

Semantic Versioning

```

MAJOR.MINOR.PATCH (e.g., 2.1.3)

MAJOR: Breaking changes

MINOR: New features (backwards compatible)

PATCH: Bug fixes (backwards compatible)

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1

Build metadata: 1.0.0+20130313144700

```

Commit Message Convention

```

():

Pitfall 1: Incomplete .gitignore

Problem: Sensitive files or build artifacts committed

Solution: Use gitignore.io templates, review before first commit

Pitfall 2: No Branch Protection

Problem: Direct pushes to main, untested code in production

Solution: Enable branch protection immediately after repo creation

Pitfall 3: Unclear Contributing Guidelines

Problem: Poor quality PRs, inconsistent code style

Solution: Detailed CONTRIBUTING.md with examples and linting automation

Pitfall 4: Missing CI/CD

Problem: Broken code merged, manual deployment friction

Solution: Set up basic CI before accepting first PR

Pitfall 5: Stale Documentation

Problem: Docs out of sync with code

Solution: Automate docs deployment, make docs updates part of PR checklist

• GitHub Docs: https://docs.github.com
• Keep a Changelog: https://keepachangelog.com
• Semantic Versioning: https://semver.org
• Contributor Covenant: https://www.contributor-covenant.org
• Citation File Format: https://citation-file-format.github.io
• GitHub Actions Marketplace: https://github.com/marketplace?type=actions

Production-ready repository includes:

1. ✅ All community health files present and complete
2. ✅ Automated testing and linting via GitHub Actions
3. ✅ Branch protection preventing untested code in main
4. ✅ Clear contribution guidelines and templates
5. ✅ GitHub Pages documentation site live
6. ✅ Proper versioning and release automation
7. ✅ Security policy and vulnerability reporting process
8. ✅ Repository discoverable via topics and description

Repository fails if:

1. ❌ Missing LICENSE or unclear licensing
2. ❌ No CI/CD, manual testing only
3. ❌ Direct commits to main possible
4. ❌ No documentation or stale docs
5. ❌ No contribution guidelines
6. ❌ Security vulnerabilities in dependencies