How We Use GitHub

GitHub is where our code lives. It's more than just storage - it's how we collaborate, review code, track work, and automate deployments.

Core idea: GitHub is your project's home base. Code, discussions, issues, and automation all live here.

GitHub vs Git

Think of it as: Git = the tool, GitHub = the platform

What is Open Source?

Open source means the source code is publicly available. Anyone can:

• View the code
• Copy it (fork)
• Suggest changes
• Use it in their projects (with license terms)

Many tools we use are open source: NextJS, Supabase, Tailwind, Shadcn UI.

Why It Matters for Us

• We can learn from how others build things
• We can report bugs and get fixes
• We can contribute improvements back
• We rely on community maintenance

Pull Requests (PRs)

A Pull Request is a proposal to merge your changes into another branch.

Why Use PRs?

1. Code review - teammates can review before merging
2. Discussion - comment on specific lines
3. CI/CD - automated tests run before merge
4. History - record of what changed and why

PR Workflow

1. Create branch → 2. Make changes → 3. Push → 4. Open PR → 5. Review → 6. Merge

Writing Good PR Descriptions

## What
Add user authentication with better-auth

## Why
Users need to log in to save their keyword clusters

## How
- Added better-auth configuration
- Created login/signup pages
- Protected dashboard routes

## Testing
- [x] Can sign up with email
- [x] Can log in
- [x] Protected routes redirect to login

GitHub Issues

Issues track bugs, features, and tasks.

Issue Types

Writing Good Issues

## Description
The keyword export fails when there are more than 1000 keywords.

## Steps to Reproduce
1. Upload CSV with 1500 keywords
2. Run clustering
3. Click "Export Results"

## Expected Behavior
CSV file downloads with all keywords

## Actual Behavior
Error: "Request too large" in console

## Environment
- Browser: Chrome 120
- Date: 2024-01-15

GitHub Actions (CI/CD)

CI/CD stands for Continuous Integration / Continuous Deployment.

• CI: Automatically test code when pushed
• CD: Automatically deploy when tests pass

How It Works

Push to GitHub → GitHub Actions runs → Tests pass → Deploy to Railway
                                    ↓
                               Tests fail → Blocked, fix needed

Basic GitHub Action

Actions are defined in .github/workflows/ files:

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Deploy to Railway
        run: railway up
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

Common Actions We Use

Daily Workflow

Starting Work

# 1. Get latest changes
git checkout main
git pull

# 2. Create feature branch
git checkout -b feature/keyword-export

# 3. Start coding (with Claude Code)

During Work

# Save progress frequently
git add .
git commit -m "WIP: export button layout"

# Push to back up your work
git push -u origin feature/keyword-export

Finishing Work

# 1. Final commit
git add .
git commit -m "Complete keyword export feature"
git push

# 2. Open PR on GitHub

# 3. After review and merge, clean up
git checkout main
git pull
git branch -d feature/keyword-export

Branch Hygiene

• Delete branches after merging
• Keep main always deployable
• Use descriptive branch names

Quick Reference

Resources

• GitHub Docs
• GitHub Skills - Interactive learning