syndarix/CONTRIBUTING.md

Contributing to FastAPI + Next.js Template

First off, thank you for considering contributing to this project! 🎉

This template aims to be a rock-solid foundation for full-stack applications, and your contributions help make that possible.

Table of Contents

• Code of Conduct
• How Can I Contribute?
• Development Setup
• Coding Standards
• Testing Guidelines
• Commit Messages
• Pull Request Process

---

Code of Conduct

This project is committed to providing a welcoming and inclusive environment. We expect all contributors to:

• Be respectful and considerate
• Welcome newcomers and help them learn
• Focus on constructive criticism
• Accept feedback gracefully
• Prioritize the community's well-being

Unacceptable behavior includes harassment, trolling, insulting comments, and personal attacks.

---

How Can I Contribute?

Reporting Bugs

Found a bug? Help us fix it!

1. Check existing issues to avoid duplicates
2. Create a new issue with:
   • Clear, descriptive title
   • Steps to reproduce
   • Expected vs. actual behavior
   • Environment details (OS, Python/Node version, etc.)
   • Screenshots/logs if applicable

Suggesting Features

Have an idea for improvement?

1. Check existing issues/discussions first
2. Open a discussion to gauge interest
3. Explain the use case and benefits
4. Consider implementation complexity

Remember: This is a template, not a full application. Features should be:

• Broadly useful
• Well-documented
• Thoroughly tested
• Maintainable long-term

Improving Documentation

Documentation improvements are always welcome!

• Fix typos or unclear explanations
• Add examples or diagrams
• Expand on complex topics
• Update outdated information
• Translate documentation (future)

Contributing Code

Ready to write some code? Awesome!

1. Pick an issue (or create one)
2. Comment that you're working on it
3. Fork and branch from main
4. Write code following our standards
5. Add tests (required for features)
6. Update docs if needed
7. Submit a PR with clear description

---

Development Setup

Backend Development

cd backend

# Install dependencies (uv manages virtual environment automatically)
uv sync

# Setup environment
cp .env.example .env
# Edit .env with your settings

# Run migrations
python migrate.py apply

# Run tests
IS_TEST=True uv run pytest

# Start dev server
uvicorn app.main:app --reload

Frontend Development

cd frontend

# Install dependencies
npm install

# Setup environment
cp .env.local.example .env.local

# Generate API client
npm run generate:api

# Run tests
npm test
npm run test:e2e:ui

# Start dev server
npm run dev

---

Coding Standards

Backend (Python)

• Style: Follow PEP 8
• Type hints: Use type annotations
• Async: Use async/await for I/O operations
• Documentation: Docstrings for all public functions/classes
• Error handling: Use custom exceptions appropriately
• Security: Never trust user input, validate everything

Example:

async def get_user_by_email(
    db: AsyncSession,
    *,
    email: str
) -> Optional[User]:
    """
    Get user by email address.

    Args:
        db: Database session
        email: User's email address

    Returns:
        User if found, None otherwise
    """
    result = await db.execute(
        select(User).where(User.email == email)
    )
    return result.scalar_one_or_none()

Frontend (TypeScript/React)

• Style: Use Prettier (configured)
• TypeScript: Strict mode, no any types
• Components: Functional components with hooks
• Naming: PascalCase for components, camelCase for functions
• Imports: Use absolute imports with @/ alias
• Dependencies: Use provided auth context (never import stores directly)

Example:

interface UserProfileProps {
  userId: string;
}

export function UserProfile({ userId }: UserProfileProps) {
  const { user } = useAuth();
  const { data, isLoading } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
  });

  if (isLoading) return <LoadingSpinner />;

  return <div>...</div>;
}

Key Patterns

• Backend: Use CRUD pattern, keep routes thin, business logic in services
• Frontend: Use React Query for server state, Zustand for client state
• Both: Handle errors gracefully, log appropriately, write tests

---

Testing Guidelines

Backend Tests

• Coverage target: >90% for new code
• Test types: Unit, integration, and security tests
• Fixtures: Use pytest fixtures from conftest.py
• Database: Use async_test_db fixture for isolation
• Assertions: Be specific about what you're testing

@pytest.mark.asyncio
async def test_create_user(client, async_test_superuser, superuser_token):
    """Test creating a new user."""
    response = await client.post(
        "/api/v1/admin/users",
        headers={"Authorization": f"Bearer {superuser_token}"},
        json={
            "email": "newuser@example.com",
            "password": "SecurePass123!",
            "first_name": "New",
            "last_name": "User"
        }
    )

    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "newuser@example.com"
    assert "password" not in data  # Never expose passwords

Frontend E2E Tests

• Use Playwright: For end-to-end user flows
• Be specific: Use accessible selectors (roles, labels)
• Be reliable: Avoid flaky tests with proper waits
• Be fast: Group related tests, use parallel execution

test('user can login and view profile', async ({ page }) => {
  // Login
  await page.goto('/auth/login');
  await page.fill('#email', 'user@example.com');
  await page.fill('#password', 'password123');
  await page.click('button[type="submit"]');

  // Should redirect to dashboard
  await expect(page).toHaveURL(/\/dashboard/);

  // Should see user name
  await expect(page.getByText('Welcome, John')).toBeVisible();
});

Unit Tests (Frontend)

• Test behavior: Not implementation details
• Mock dependencies: Use Jest mocks appropriately
• Test accessibility: Include a11y checks when relevant

---

Commit Messages

Write clear, descriptive commit messages:

Format

<type>: <subject>

<body (optional)>

<footer (optional)>

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, no logic change)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples

Good:

feat: add password reset flow

Implements complete password reset with email tokens.
Tokens expire after 1 hour for security.

Closes #123

Also good (simple change):

fix: correct pagination offset calculation

Not great:

Fixed stuff

---

Pull Request Process

Before Submitting

• Code follows project style guidelines
• All tests pass locally
• New tests added for new features
• Documentation updated if needed
• No merge conflicts with main
• Commits are logical and well-described

PR Template

## Description
Brief description of changes

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

## Testing
How was this tested?

## Screenshots (if applicable)

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] No breaking changes
- [ ] Follows coding standards

Review Process

1. Submit PR with clear description
2. CI checks must pass (when implemented)
3. Code review by maintainers
4. Address feedback if requested
5. Approval from at least one maintainer
6. Merge by maintainer

After Merge

• Your contribution will be in the next release
• You'll be added to contributors list
• Feel awesome! 🎉

---

Questions?

• Documentation issues? Ask in your PR or issue
• Unsure about implementation? Open a discussion first
• Need help? Tag maintainers in your issue/PR

---

Recognition

Contributors are recognized in:

• GitHub contributors page
• Release notes (for significant contributions)
• README acknowledgments (for major features)

---

Thank you for contributing! Every contribution, no matter how small, makes this template better for everyone. 🚀