forked from cardosofelipe/fast-next-template
Felipe Cardoso
a7ba0f9bd8
- Create docs/development/WORKFLOW.md with branch strategy, issue management, testing requirements, and code review process - Create docs/development/CODING_STANDARDS.md with technical patterns, auth DI pattern, testing patterns, and security guidelines - Streamline CLAUDE.md to link to detailed documentation instead of embedding all content - Add branch/issue workflow rules: single branch per feature for both design and implementation phases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
229 lines
6.0 KiB
Markdown
229 lines
6.0 KiB
Markdown
# Development Workflow
|
|
|
|
This document defines the development workflow, branching strategy, and issue management rules for Syndarix.
|
|
|
|
## Issue-Driven Development
|
|
|
|
**Every piece of work MUST have an issue in the Gitea tracker first.**
|
|
|
|
- Issue tracker: https://gitea.pragmazest.com/cardosofelipe/syndarix/issues
|
|
- Create detailed, well-scoped issues before starting work
|
|
- Structure issues to enable parallel work by multiple agents
|
|
- Reference issues in commits and PRs
|
|
|
|
---
|
|
|
|
## Git Branching Strategy
|
|
|
|
### Branch Naming Convention
|
|
|
|
```
|
|
feature/<issue-number>-<short-description>
|
|
```
|
|
|
|
Examples:
|
|
- `feature/123-user-authentication`
|
|
- `feature/456-project-dashboard`
|
|
|
|
### Branch Workflow
|
|
|
|
```
|
|
main (production-ready)
|
|
└── dev (integration branch)
|
|
└── feature/123-description (issue branch)
|
|
```
|
|
|
|
### Rules
|
|
|
|
1. **Every issue gets its own feature branch**
|
|
2. **No direct commits to `main` or `dev`**
|
|
3. **Keep branches focused and small**
|
|
4. **Delete branches after merge**
|
|
5. **All branches must be mergeable to dev** - if work isn't ready to merge, keep it in a separate branch
|
|
|
|
---
|
|
|
|
## Issue and Branch Structure for Features
|
|
|
|
### Single Branch per Feature
|
|
|
|
For UI/UX features that require both design and implementation:
|
|
|
|
1. **Create a single feature branch** for both design prototype and implementation
|
|
2. **Do NOT create separate branches** for design vs implementation
|
|
|
|
### Issue Structure Options
|
|
|
|
Choose one of these approaches based on complexity:
|
|
|
|
#### Option A: Single Issue with Tasks (Recommended for most features)
|
|
|
|
```markdown
|
|
## Issue: Add User Profile Page (#123)
|
|
|
|
### Tasks
|
|
- [ ] Design: Create interactive prototype in /prototypes
|
|
- [ ] Design: Get user approval on the design
|
|
- [ ] Implementation: Build page following design system
|
|
- [ ] Implementation: Write tests
|
|
- [ ] Cleanup: Remove prototype after implementation
|
|
```
|
|
|
|
Branch: `feature/123-user-profile-page`
|
|
|
|
#### Option B: User Story with Sub-Issues (For complex features)
|
|
|
|
```markdown
|
|
## User Story: Project Management (#100)
|
|
├── Sub-issue: Design project dashboard (#101)
|
|
├── Sub-issue: Implement project dashboard (#102)
|
|
├── Sub-issue: Design project settings (#103)
|
|
└── Sub-issue: Implement project settings (#104)
|
|
```
|
|
|
|
Branch: `feature/100-project-management` (single branch for the entire user story)
|
|
|
|
**Important:** Even with multiple sub-issues, use a **single branch** for the user story.
|
|
|
|
---
|
|
|
|
## UI/UX Design Workflow
|
|
|
|
### For New UI Features
|
|
|
|
1. **Create Issue**: Use `design` label
|
|
2. **Build Prototype**: Create in `/frontend/src/app/[locale]/prototypes/<feature>/`
|
|
3. **User Review**: Get feedback on the prototype
|
|
4. **Approval**: User approves design before implementation
|
|
5. **Implementation**: Build in production location following design system
|
|
6. **Cleanup**: Remove prototype after implementation
|
|
|
|
### Design Guidelines
|
|
|
|
| Phase | Requirements |
|
|
|-------|-------------|
|
|
| **Prototype** | Best effort to match design system (not required) |
|
|
| **Production** | MUST follow `frontend/docs/design-system/` strictly |
|
|
|
|
---
|
|
|
|
## Testing Requirements
|
|
|
|
**All code must be tested. No exceptions.**
|
|
|
|
### Testing Approach
|
|
|
|
- **TDD preferred**: Write tests first when possible
|
|
- **Test after**: If not TDD, write tests immediately after testable code
|
|
- **Coverage types**: Unit, integration, functional, E2E as appropriate
|
|
- **Minimum coverage**: Aim for >90% on new code
|
|
|
|
### Testing Commands
|
|
|
|
```bash
|
|
# Backend
|
|
IS_TEST=True uv run pytest # Unit/integration tests
|
|
make test-e2e # E2E tests (requires Docker)
|
|
|
|
# Frontend
|
|
npm test # Unit tests
|
|
npm run test:e2e # E2E tests
|
|
```
|
|
|
|
---
|
|
|
|
## Code Review Process
|
|
|
|
**Before merging any feature branch, code must pass multi-agent review:**
|
|
|
|
| Check | Description |
|
|
|-------|-------------|
|
|
| Bug hunting | Logic errors, edge cases, race conditions |
|
|
| Linting | `ruff check` / `eslint` passes with no errors |
|
|
| Typing | `mypy` / `tsc --noEmit` passes with no errors |
|
|
| Formatting | Code follows style guidelines |
|
|
| Performance | No obvious bottlenecks or N+1 queries |
|
|
| Security | No vulnerabilities (OWASP top 10) |
|
|
| Architecture | Follows established patterns and ADRs |
|
|
|
|
**Issue is NOT done until review passes with flying colors.**
|
|
|
|
---
|
|
|
|
## QA Before Main
|
|
|
|
**Before merging `dev` into `main`:**
|
|
|
|
- [ ] Full test suite passes
|
|
- [ ] Manual QA verification
|
|
- [ ] Performance baseline check
|
|
- [ ] Security scan
|
|
- [ ] Code must be clean, functional, bug-free, well-architected, and secure
|
|
|
|
---
|
|
|
|
## Commit Message Format
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[optional body]
|
|
|
|
[optional footer]
|
|
```
|
|
|
|
### Types
|
|
|
|
- `feat`: New feature
|
|
- `fix`: Bug fix
|
|
- `docs`: Documentation only
|
|
- `style`: Formatting, missing semicolons, etc.
|
|
- `refactor`: Code change that neither fixes a bug nor adds a feature
|
|
- `test`: Adding missing tests
|
|
- `chore`: Maintenance tasks
|
|
|
|
### Examples
|
|
|
|
```
|
|
feat(auth): add password reset functionality
|
|
fix(api): handle null response in user endpoint
|
|
docs(readme): update installation instructions
|
|
test(frontend): add unit tests for ProjectDashboard
|
|
```
|
|
|
|
---
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Create PR from feature branch to dev**
|
|
2. **PR title**: Same format as commit messages
|
|
3. **PR body**: Include summary, test plan, and issue reference
|
|
4. **Wait for CI**: All checks must pass
|
|
5. **Code review**: Address all feedback
|
|
6. **Merge**: Squash and merge when approved
|
|
7. **Cleanup**: Delete feature branch after merge
|
|
|
|
---
|
|
|
|
## Documentation Updates
|
|
|
|
- Keep `docs/architecture/IMPLEMENTATION_ROADMAP.md` updated
|
|
- Mark completed items as work progresses
|
|
- Add new items discovered during implementation
|
|
- Update ADRs when architectural decisions change
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
| Action | Command/Location |
|
|
|--------|-----------------|
|
|
| Create branch | `git checkout -b feature/<issue>-<desc>` |
|
|
| Run backend tests | `IS_TEST=True uv run pytest` |
|
|
| Run frontend tests | `npm test` |
|
|
| Check types (backend) | `uv run mypy src/` |
|
|
| Check types (frontend) | `npm run type-check` |
|
|
| Lint (backend) | `uv run ruff check src/` |
|
|
| Lint (frontend) | `npm run lint` |
|
|
| Generate API client | `npm run generate:api` |
|