Development Workflow

Learn the recommended development process, branching strategy, and collaboration patterns for Portfolio OS.

Branching Strategy

Portfolio OS uses a Git Flow-inspired branching model:

Branch Types

Workflow Steps

git checkout develop
git pull origin develop
git checkout -b feature/add-dark-mode

# Make changes
git add .
git commit -m "feat(site): add dark mode toggle"

git checkout develop
git pull origin develop
git checkout feature/add-dark-mode
git rebase develop

git push origin feature/add-dark-mode
# Then create PR on GitHub

Commit Convention

Portfolio OS follows Conventional Commits specification.

Commit Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Types

Scopes

Common scopes in Portfolio OS:

• site - Site app
• dashboard - Dashboard app
• docs - Documentation app
• ui - UI package
• lib - Lib package
• db - Database package
• scripts - Automation scripts

Examples

feat(site): add RSS feed for blog posts

fix(dashboard): resolve media upload timeout

docs(getting-started): add environment setup guide

refactor(ui): extract button variants to shared config

perf(site): implement Redis caching for blog posts
Reduces page load time by 60%
Closes #123

chore(deps): upgrade Next.js to 14.2.32

test(lib): add integration tests for Hashnode client

Pull Request Process

Creating a PR

# Ensure tests pass
pnpm test

# Ensure linting passes
pnpm lint

# Type check
pnpm typecheck

# Build to catch errors
pnpm build

git push origin feature/your-feature

feat(scope): Brief description

## What
Brief description of what this PR does

## Why
Explanation of why this change is needed

## How
Technical approach and implementation details

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Screenshots
(if applicable)

## Breaking Changes
(if any)

Closes #issue_number

git add .
git commit -m "fix: address review comments"
git push origin feature/your-feature

PR Checklist

Before requesting review, ensure:

• Code follows coding standards
• Tests are added/updated and passing
• Documentation is updated
• No console errors or warnings
• Build passes successfully
• Linting passes
• TypeScript has no errors
• Commit messages follow convention
• PR description is complete

Review Guidelines

For Reviewers:

1. Code Quality: Check for clarity, maintainability
2. Testing: Verify adequate test coverage
3. Performance: Look for potential bottlenecks
4. Security: Check for vulnerabilities
5. Documentation: Ensure changes are documented

Providing Feedback:

✅ Good: "Consider extracting this logic into a separate function for reusability"
❌ Bad: "This code is bad"

✅ Good: "This could cause a memory leak. Try using useEffect cleanup"
❌ Bad: "Won't work"

Release Process

Version Numbers

Portfolio OS follows Semantic Versioning:

• Major (x.0.0): Breaking changes
• Minor (0.x.0): New features (backward compatible)
• Patch (0.0.x): Bug fixes

Creating a Release

git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

# Update package.json versions
# Update CHANGELOG.md

pnpm install
pnpm build
pnpm test
# Manual testing

git checkout main
git merge release/v1.2.0
git tag v1.2.0
git push origin main --tags

git checkout develop
git merge main
git push origin develop

Hotfix Process

For critical production bugs:

git checkout main
git checkout -b hotfix/critical-security-fix

# Make fix
git commit -m "fix: resolve critical security vulnerability"
pnpm test

git checkout main
git merge hotfix/critical-security-fix
git tag v1.2.1
git push origin main --tags

git checkout develop
git merge hotfix/critical-security-fix
git push origin develop

Development Best Practices

1. Small, Focused PRs

2. Regular Commits

Commit frequently with meaningful messages:

git commit -m "feat(site): add dark mode context"
git commit -m "feat(site): implement theme toggle button"
git commit -m "feat(site): persist theme preference"
git commit -m "test(site): add dark mode tests"

3. Keep Dependencies Updated

# Check for outdated packages
pnpm outdated

# Update safely
pnpm update --latest --interactive

4. Sync Frequently

# Sync with develop daily
git checkout develop
git pull origin develop
git checkout your-branch
git rebase develop

Automation Tools

Portfolio OS includes PowerShell scripts for common workflows:

# Create new feature branch
.\scripts\branch-management\create-branch.ps1 -Type feature -Name "add-comments"

# Create PR
.\scripts\pr-management\create-pr.ps1 -Title "feat(blog): add comment system"

# Sync all worktrees
.\scripts\agent-management\sync-agents.ps1

See Scripts Reference for details.

Multi-Agent Development

For parallel development with multiple agents:

# Create agent worktree
.\scripts\agent-management\create-agent.ps1 -AgentName "agent-1"

# Assign task to agent
.\scripts\agent-management\assign-task.ps1 -AgentName "agent-1" -Task "Implement dark mode"

See Multi-Agent System for more.

Next Steps

• Coding Standards - Learn code quality guidelines
• Monorepo Structure - Understand workspace organization
• Scripts Reference - Explore automation tools