QuantEngineByItz/oms-wms-erp/GITHUB-SETUP.md

# GitHub Setup Guide

**Complete GitHub repository configuration for OMS·WMS·ERP**

---

## 1. Repository Settings

### Basic Settings
- **Repository Name**: `oms-wms-erp`
- **Description**: Enterprise OMS·WMS·ERP Platform (Vue 3 + TypeScript)
- **Visibility**: Private (internal use only)
- **Default Branch**: `main`
- **Squash merges**: Enabled (keep commit history clean)
- **Auto-delete head branches**: Enabled (cleanup after PR merge)

### Repository Collaborators

Add team members with appropriate roles:

| Role | Responsibility |
|------|-----------------|
| **Admin** | Release management, workflow updates, settings |
| **Maintain** | Code review, PR approval, branch management |
| **Triage** | Label management, issue assignment |
| **Push** | Push to main, create branches, PR reviews |
| **Pull** | Clone, pull, create issues/discussions |

---

## 2. Branch Protection Rules

### Rule 1: Protect `main` Branch

Navigate to: **Settings → Branches → Add rule**

```
Branch name pattern: main
```

Enable:
- ✅ **Require a pull request before merging**
  - Require approvals: 1
  - Require review from code owners: Yes
  - Dismiss stale pull request approvals: Yes

- ✅ **Require status checks to pass before merging**
  - Require branches to be up to date: Yes
  - Required status checks:
    - `lint` (ESLint)
    - `test` (Unit tests)
    - `build` (Production build)
    - `storybook` (Storybook build)
    - `accessibility` (A11y audit)

- ✅ **Require code reviews**
  - Require 1 approval minimum
  - Require review from CODEOWNERS: Yes

- ✅ **Require signed commits**: No (optional)

- ✅ **Require resolution of conversations**: Yes

### Rule 2: Protect `develop` Branch (if used)

```
Branch name pattern: develop
```

Enable:
- ✅ Require PR before merge
- ✅ Require 1 approval
- ✅ Status checks (same as main)

---

## 3. CODEOWNERS File

Create `.github/CODEOWNERS`:

```
# Root configuration
* @frontend-team
*.json @frontend-team
*.yml @frontend-team

# Components
/src/components/primitives/ @frontend-lead
/src/components/fields/ @frontend-team
/src/components/composites/ @frontend-team

# Stores & Services
/src/stores/ @frontend-team
/src/services/ @frontend-team

# Tests
/tests/ @qa-team

# Documentation
/docs/ @technical-writer
DEVELOPMENT.md @frontend-lead
README.md @frontend-lead
```

---

## 4. GitHub Actions Secrets

Navigate to: **Settings → Secrets and variables → Actions**

### Required Secrets (None for public actions)

- `CODECOV_TOKEN` (optional, for coverage reporting)
  - Get from: https://codecov.io (if using Codecov)

### Optional Secrets (for future phases)

- `SENTRY_DSN` (error tracking)
- `GA_ID` (analytics)
- `NPM_TOKEN` (if publishing to npm)

---

## 5. Workflow Configuration

### Workflows Location
All workflows in `.github/workflows/`:

| Workflow | Trigger | Purpose |
|----------|---------|---------|
| **ci.yml** | push (main/develop), PR | Lint → Test → Build → A11y |
| **deploy-storybook.yml** | push (main) | Build & deploy to GitHub Pages |

### Workflow Triggers

**CI Workflow** (ci.yml)
```yaml
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
```

**Deploy Storybook** (deploy-storybook.yml)
```yaml
on:
  push:
    branches: [main]
    paths:
      - 'src/components/**'
      - '.storybook/**'
```

---

## 6. GitHub Pages Deployment (Storybook)

### Enable GitHub Pages

Navigate to: **Settings → Pages**

```
Source: Deploy from a branch
Branch: gh-pages (auto-created by deploy-storybook.yml)
Folder: / (root)
Enforce HTTPS: Yes
```

### Access Storybook

After first deployment:
```
https://<username>.github.io/<repo-name>/
```

Example: `https://kjh2064.github.io/oms-wms-erp/`

---

## 7. Environment Setup

### Development Environment

1. **Clone repository**
   ```bash
   git clone https://github.com/<username>/oms-wms-erp.git
   cd oms-wms-erp
   ```

2. **Copy environment file**
   ```bash
   cp .env.example .env.local
   ```

3. **Install & verify**
   ```bash
   make verify-step2
   ```

### CI/CD Environment

Workflows run automatically on:
- Every push to `main` or `develop`
- Every pull request to `main` or `develop`

No additional setup needed — GitHub Actions handles it.

---

## 8. PR Template

Create `.github/pull_request_template.md`:

```markdown
## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Closes #(issue number)

## Testing
- [ ] Unit tests pass (npm run test:unit)
- [ ] E2E tests pass (npm run test:e2e)
- [ ] Storybook stories updated
- [ ] No console errors

## Checklist
- [ ] Code follows project style (npm run lint passes)
- [ ] Documentation updated
- [ ] All tests passing
- [ ] No new warnings
- [ ] Accessibility verified (axe-core)

## Screenshots (if applicable)
Add screenshots for UI changes.
```

---

## 9. Issue Templates

Create `.github/ISSUE_TEMPLATE/bug_report.md`:

```markdown
---
name: Bug Report
about: Report a bug
title: '[BUG] '
labels: bug
---

## Description
Brief description of the bug.

## Steps to Reproduce
1. Step 1
2. Step 2
3. Step 3

## Expected Behavior
What should happen.

## Actual Behavior
What actually happened.

## Screenshots
If applicable, add screenshots.

## Environment
- Node version: (e.g., 18.0.0)
- Browser: (e.g., Chrome 120)
- OS: (e.g., macOS)
```

Create `.github/ISSUE_TEMPLATE/feature_request.md`:

```markdown
---
name: Feature Request
about: Suggest an enhancement
title: '[FEATURE] '
labels: enhancement
---

## Description
Brief description of the feature.

## Motivation
Why is this feature needed?

## Proposed Solution
How should it work?

## Alternatives
Other possible approaches?
```

---

## 10. Monitoring & Maintenance

### Check Workflow Status

1. **GitHub Actions Dashboard**
   ```
   https://github.com/<username>/oms-wms-erp/actions
   ```

2. **View workflow run details**
   - Click workflow name
   - See jobs and logs
   - Diagnose failures

### Common Issues

| Issue | Solution |
|-------|----------|
| Build timeout | Increase timeout or optimize dependencies |
| npm install fails | Check internet connection, clear npm cache |
| Port already in use | Change port in vite.config.ts |
| Test flakiness | Retry test, check for async issues |

### Monitoring

- **codecov.io** (optional) - Track test coverage over time
- **GitHub Insights** - Monitor pull requests, contributors
- **GitHub Pages** - Monitor Storybook deployment status

---

## 11. Team Workflow

### Feature Branch Workflow

```
1. Create feature branch
   git checkout -b feat/component-name

2. Develop & commit
   git commit -m "feat(component): description"

3. Push to GitHub
   git push origin feat/component-name

4. Create Pull Request
   - GitHub will run CI/CD checks automatically
   - All checks must PASS
   - Require 1 code review approval

5. Merge to main
   - Squash merge (keeps history clean)
   - Delete branch after merge
   - Storybook auto-deploys

6. Release (manual)
   - Tag commit: git tag v0.1.0
   - Push tag: git push origin v0.1.0
```

### Code Review Process

1. **Author** creates PR with description
2. **Reviewers** check:
   - ✅ Code quality (ESLint passes)
   - ✅ Tests passing (100% for critical paths)
   - ✅ Accessibility (WCAG 2.1 AA)
   - ✅ Documentation updated
3. **CI/CD** verifies:
   - ✅ All status checks PASS
   - ✅ No merge conflicts
4. **Merge** to main (squash commit)
5. **Deploy** Storybook auto-deploys

---

## 12. Release Process

### Create Release

```bash
# 1. Create version tag
git tag -a v0.1.0 -m "Release v0.1.0"

# 2. Push tag
git push origin v0.1.0

# 3. GitHub auto-creates release
# Visit: https://github.com/<username>/oms-wms-erp/releases
```

### Release Checklist

- [ ] All tests passing
- [ ] No critical warnings
- [ ] Storybook built & deployed
- [ ] Documentation updated
- [ ] Version bumped in package.json
- [ ] CHANGELOG updated
- [ ] Tag created & pushed

---

## 13. Troubleshooting

### Workflow Failures

**Check logs:**
```
GitHub Actions → Workflow → Job → Logs
```

**Common failures:**
- `lint` failure: Run `npm run lint -- --fix`
- `test` failure: Run `npm run test:unit`
- `build` failure: Check dependencies, run `npm ci`

### Branch Protection Issues

If you can't merge PR:
1. Verify all checks PASS
2. Ensure 1 approval received
3. Check branch is up-to-date
4. Resolve conversations

---

## 14. Best Practices

### Commit Messages
```
feat(component): Add new Button component
fix(button): Correct loading state
docs: Update component guide
test: Add Button unit tests
chore: Update dependencies
```

### Branch Naming
```
feat/button-component
fix/button-loading-state
docs/add-guide
refactor/simplify-input
```

### PR Titles
```
[FEAT] Add Button primitive component
[FIX] Correct Table row-click event
[DOCS] Update development guide
[TEST] Add E2E tests for Order form
```

---

## Phase 1 GitHub Setup Checklist

- [ ] Repository created (main branch)
- [ ] Branch protection rule applied to main
- [ ] CODEOWNERS file created
- [ ] GitHub Pages enabled
- [ ] CI/CD workflows created (.github/workflows/)
- [ ] .env.example committed
- [ ] PR template added (.github/pull_request_template.md)
- [ ] Issue templates added (.github/ISSUE_TEMPLATE/)
- [ ] All team members invited & permissions set
- [ ] First Storybook deploy successful
- [ ] All workflows passing on main

---

**Status**: ✅ Phase 1 Step 4 Ready  
**Timeline**: 2026-08-11 (Week 2, Friday)  
**Next**: Phase 2 (Typed Fields, Week 3-4)