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)

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

Deploy Storybook (deploy-storybook.yml)

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

   git clone https://github.com/<username>/oms-wms-erp.git
   cd oms-wms-erp
   

2. Copy environment file

   cp .env.example .env.local
   

3. Install & verify

   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:

## 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:

---
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:

---
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

# 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)