Skip to content

Commit b81a5e4

Browse files
wagnertclaude
wagnert
and
claude
committed
feat: add Git-Flow, CI/CD, testing infrastructure, and comprehensive documentation
Major improvements to project structure and development workflow: Git-Flow & CI/CD: - Implement Git-Flow with develop → staging → main branches - Add GitHub Actions workflows for CI, staging, and production deployments - Configure branch protection rules and environment-based deployments - Add automated release workflow with changelog generation Testing Infrastructure: - Separate tests from source code (tests/ directory) - Add AppSheetClientInterface for polymorphic client usage - Create MockAppSheetClient with in-memory storage for testing - Add comprehensive test suite (48 tests) with JSDoc documentation - Fix Jest/ES module compatibility with uuid mock Documentation: - Add CONTRIBUTING.md with Git-Flow and Semantic Versioning guidelines - Add CHANGELOG.md with version history template - Create .github/GIT-FLOW.md quick reference - Create .github/BRANCH-PROTECTION.md configuration guide - Add comprehensive JSDoc comments to all test files - Update README.md with Git-Flow and versioning sections - Update CLAUDE.md with Git-Flow strategy Semantic Versioning: - Add npm scripts for version management (patch/minor/major/prerelease) - Configure automated release process - Add Conventional Commits guidelines Additional: - Initialize time-tracking configuration - Add .claude/ to .gitignore - Update TypeScript configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent d99f80c commit b81a5e4

27 files changed

+4330
-378
lines changed

‎.github/BRANCH-PROTECTION.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Branch Protection Configuration
2+
3+
Configure these settings in **GitHub Repository Settings → Branches → Branch protection rules**.
4+
5+
## `develop` Branch Protection
6+
7+
1. Go to: Settings → Branches → Add rule
8+
2. Branch name pattern: `develop`
9+
3. Configure:
10+
11+
```
12+
✅ Require a pull request before merging
13+
✅ Require approvals: 1
14+
✅ Dismiss stale pull request approvals when new commits are pushed
15+
✅ Require approval of the most recent reviewable push
16+
17+
✅ Require status checks to pass before merging
18+
✅ Require branches to be up to date before merging
19+
Status checks:
20+
- test (Node.js 18.x)
21+
- test (Node.js 20.x)
22+
- test (Node.js 22.x)
23+
- coverage
24+
25+
✅ Require conversation resolution before merging
26+
27+
✅ Include administrators
28+
29+
❌ Allow force pushes (disabled)
30+
❌ Allow deletions (disabled)
31+
```
32+
33+
**Deployment:** ❌ No automatic deployment (CI only)
34+
35+
---
36+
37+
## `staging` Branch Protection
38+
39+
1. Go to: Settings → Branches → Add rule
40+
2. Branch name pattern: `staging`
41+
3. Configure:
42+
43+
```
44+
✅ Require a pull request before merging
45+
✅ Require approvals: 1
46+
✅ Dismiss stale pull request approvals when new commits are pushed
47+
✅ Require approval of the most recent reviewable push
48+
49+
✅ Require status checks to pass before merging
50+
✅ Require branches to be up to date before merging
51+
Status checks:
52+
- test (Node.js 18.x)
53+
- test (Node.js 20.x)
54+
- test (Node.js 22.x)
55+
- coverage
56+
57+
✅ Require conversation resolution before merging
58+
59+
✅ Restrict who can push to matching branches (optional)
60+
Allowed: develop branch only
61+
62+
✅ Include administrators
63+
64+
❌ Allow force pushes (disabled)
65+
❌ Allow deletions (disabled)
66+
```
67+
68+
**Deployment:** ✅ Auto-deploy to Staging environment
69+
70+
---
71+
72+
## `main` Branch Protection
73+
74+
1. Go to: Settings → Branches → Add rule
75+
2. Branch name pattern: `main`
76+
3. Configure:
77+
78+
```
79+
✅ Require a pull request before merging
80+
✅ Require approvals: 2 (WICHTIG: 2 Approver!)
81+
✅ Dismiss stale pull request approvals when new commits are pushed
82+
✅ Require approval of the most recent reviewable push
83+
✅ Require review from Code Owners (optional)
84+
85+
✅ Require status checks to pass before merging
86+
✅ Require branches to be up to date before merging
87+
Status checks:
88+
- test (Node.js 18.x)
89+
- test (Node.js 20.x)
90+
- test (Node.js 22.x)
91+
- coverage
92+
93+
✅ Require conversation resolution before merging
94+
95+
✅ Require deployments to succeed before merging
96+
Required deployment environments:
97+
- staging
98+
99+
✅ Restrict who can push to matching branches (optional)
100+
Allowed: staging branch, hotfix/* branches
101+
102+
✅ Include administrators
103+
104+
❌ Allow force pushes (disabled)
105+
❌ Allow deletions (disabled)
106+
```
107+
108+
**Deployment:** ✅ Auto-deploy to Production environment
109+
110+
---
111+
112+
## Environment Configuration
113+
114+
Configure these in **Settings → Environments**:
115+
116+
### Staging Environment
117+
118+
```
119+
Name: staging
120+
Protection rules:
121+
✅ Required reviewers: 1
122+
✅ Wait timer: 0 minutes
123+
124+
Environment secrets:
125+
- STAGING_TOKEN (if needed)
126+
```
127+
128+
### Production Environment
129+
130+
```
131+
Name: production
132+
Protection rules:
133+
✅ Required reviewers: 2
134+
✅ Wait timer: 5 minutes (optional safety delay)
135+
136+
Environment secrets:
137+
- NPM_TOKEN (for npm publishing)
138+
- PRODUCTION_TOKEN (if needed)
139+
```
140+
141+
---
142+
143+
## CODEOWNERS File (Optional)
144+
145+
Create `.github/CODEOWNERS` to automatically request reviews:
146+
147+
```
148+
# Default owners for everything
149+
* @team-lead @senior-dev
150+
151+
# Specific files
152+
/.github/ @devops-team
153+
/docs/ @documentation-team
154+
```
155+
156+
---
157+
158+
## Verification
159+
160+
After configuring, verify:
161+
162+
1. ✅ Try to push directly to `develop` (should fail)
163+
2. ✅ Try to push directly to `staging` (should fail)
164+
3. ✅ Try to push directly to `main` (should fail)
165+
4. ✅ Create PR without CI passing (should be blocked)
166+
5. ✅ Create PR without reviews (should be blocked)
167+
168+
---
169+
170+
## Quick Reference
171+
172+
| Branch | Reviewers | Status Checks | Force Push | Deploy |
173+
|-----------|-----------|---------------|------------|--------|
174+
| `develop` | 1 | ✅ | ❌ | ❌ |
175+
| `staging` | 1 | ✅ | ❌ | ✅ |
176+
| `main` | 2 | ✅ | ❌ | ✅ |

‎.github/GIT-FLOW.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Git-Flow Quick Reference
2+
3+
## Branch Strategy
4+
5+
```
6+
develop → CI only (keine Deployments)
7+
staging → Staging Deployment (Pre-Production)
8+
main → Production Deployment
9+
```
10+
11+
## Branch Flow
12+
13+
```mermaid
14+
graph LR
15+
F[feature/*] --> D[develop]
16+
D --> S[staging]
17+
S --> M[main]
18+
M -.hotfix.-> D
19+
```
20+
21+
## Quick Commands
22+
23+
### Start New Feature
24+
```bash
25+
git checkout develop
26+
git pull origin develop
27+
git checkout -b feature/my-feature
28+
# ... work ...
29+
git push origin feature/my-feature
30+
# Create PR: feature/my-feature → develop
31+
```
32+
33+
### Promote to Staging
34+
```bash
35+
git checkout staging
36+
git pull origin staging
37+
git merge develop
38+
git push origin staging
39+
# Or: Create PR: develop → staging
40+
# 🚀 Auto-deploys to staging
41+
```
42+
43+
### Promote to Production
44+
```bash
45+
git checkout main
46+
git pull origin main
47+
git merge staging
48+
git push origin main
49+
# Or: Create PR: staging → main
50+
# 🚀 Auto-deploys to production
51+
```
52+
53+
### Hotfix Production
54+
```bash
55+
git checkout main
56+
git pull origin main
57+
git checkout -b hotfix/critical-fix
58+
# ... fix ...
59+
git push origin hotfix/critical-fix
60+
# Create PR: hotfix/critical-fix → main
61+
# Then merge main back to develop
62+
```
63+
64+
## Branch Protection
65+
66+
| Branch | Reviewers | CI Required | Deploy |
67+
|-----------|-----------|-------------|--------|
68+
| `develop` | 1 | ✅ | ❌ |
69+
| `staging` | 1 | ✅ | ✅ |
70+
| `main` | 2 | ✅ | ✅ |
71+
72+
## Workflow Overview
73+
74+
```
75+
1. Feature Development: feature/xxx → develop (CI only)
76+
2. Staging Testing: develop → staging (Deploy + Test)
77+
3. Production Release: staging → main (Deploy to Prod)
78+
```
79+
80+
## CI/CD Matrix
81+
82+
| Event | Branch | CI | Deploy | Environment |
83+
|--------------------|-----------|-----|--------|-------------|
84+
| PR created | Any | ✅ | ❌ | None |
85+
| PR merged | develop | ✅ | ❌ | None |
86+
| PR merged | staging | ✅ | ✅ | Staging |
87+
| PR merged | main | ✅ | ✅ | Production |
88+
89+
## Need Help?
90+
91+
See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed workflow documentation.

‎.github/workflows/ci.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main, staging, develop ]
6+
pull_request:
7+
branches: [ main, staging, develop ]
8+
9+
jobs:
10+
test:
11+
name: Test on Node.js ${{ matrix.node-version }}
12+
runs-on: ubuntu-latest
13+
14+
strategy:
15+
matrix:
16+
node-version: [18.x, 20.x, 22.x]
17+
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Node.js ${{ matrix.node-version }}
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: ${{ matrix.node-version }}
26+
cache: 'npm'
27+
28+
- name: Install dependencies
29+
run: npm ci
30+
31+
- name: Run linter
32+
run: npm run lint
33+
34+
- name: Run build
35+
run: npm run build
36+
37+
- name: Run tests
38+
run: npm test
39+
40+
- name: Check CLI binary
41+
run: |
42+
chmod +x dist/cli/index.js
43+
node dist/cli/index.js --version || echo "CLI check skipped"
44+
45+
coverage:
46+
name: Code Coverage
47+
runs-on: ubuntu-latest
48+
49+
steps:
50+
- name: Checkout code
51+
uses: actions/checkout@v4
52+
53+
- name: Setup Node.js
54+
uses: actions/setup-node@v4
55+
with:
56+
node-version: '20.x'
57+
cache: 'npm'
58+
59+
- name: Install dependencies
60+
run: npm ci
61+
62+
- name: Run tests with coverage
63+
run: npm test -- --coverage
64+
65+
- name: Upload coverage reports
66+
uses: codecov/codecov-action@v4
67+
if: success()
68+
with:
69+
files: ./coverage/lcov.info
70+
fail_ci_if_error: false
71+
continue-on-error: true

0 commit comments

Comments
 (0)