Contributing to FastAPI RBAC¶

Thank you for your interest in contributing to the FastAPI RBAC project! We're excited to have you join our community and look forward to your contributions. This guide will help you get started and ensure your contributions align with our project standards.

Table of Contents¶

Welcome
Project Overview
How to Contribute
Getting Started
Development Guidelines
Code Standards
Testing Requirements
Submission Process
Release Process
Community Guidelines
Getting Help
Recognition

Welcome¶

FastAPI RBAC is a comprehensive Role-Based Access Control system with a FastAPI backend and React frontend, designed to handle authentication and authorization for microservices. Our mission is to provide a secure, scalable, and developer-friendly RBAC solution that follows enterprise security standards.

What We Accept¶

We welcome the following types of contributions:

🐛 Bug Reports: Issues with existing functionality
✨ Feature Requests: New features and enhancements
🔧 Code Contributions: Bug fixes, new features, performance improvements
📚 Documentation: Improvements to guides, API docs, and tutorials
🧪 Tests: Additional test coverage and test improvements
🔒 Security: Security improvements and vulnerability reports
🎨 UI/UX: Frontend improvements and accessibility enhancements
🌐 Frontend Development: React/TypeScript contributions
⚙️ DevOps: Docker, CI/CD, and deployment improvements

What We Don't Accept¶

At this time, we do not accept the following:

Translations: We currently support English only
Major architectural changes without prior discussion
Breaking changes to existing APIs without migration plans
Dependencies that conflict with our security requirements

Project Overview¶

Technology Stack¶

Backend (FastAPI):

FastAPI with Python 3.10+
PostgreSQL with SQLAlchemy/SQLModel
Redis for caching and token management
Celery for background tasks
JWT authentication with bcrypt
Comprehensive security features (CSRF, XSS protection, rate limiting)

Frontend (React):

React 18+ with TypeScript
Redux Toolkit for state management
ShadCN UI with Tailwind CSS
Vite build system
Comprehensive test suite with Vitest

Project Structure¶

fastapi_rbac/
├── 📁 backend/              # FastAPI application
├── 📁 react-frontend/       # React TypeScript app
├── 📁 docs/                # Documentation
├── 📁 scripts/             # Utility scripts
└── 📄 docker-compose*.yml  # Container configurations

How to Contribute¶

1. Report Issues¶

Found a bug or have a feature request? Please check our issue tracker first to avoid duplicates.

For Bug Reports, please include:

Clear description of the issue
Steps to reproduce
Expected vs actual behavior
Environment details (OS, Docker version, etc.)
Relevant logs or error messages

For Feature Requests, please include:

Clear description of the proposed feature
Use cases and benefits
Potential implementation approach
Consideration for backward compatibility

2. Submit Code Changes¶

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes following our development guidelines
Test your changes thoroughly
Commit your changes: git commit -m 'feat: add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Submit a Pull Request

3. Improve Documentation¶

Documentation improvements are always welcome! You can:

Fix typos or unclear explanations
Add missing documentation
Update outdated information
Create new guides or tutorials

Getting Started¶

Prerequisites¶

Git for version control
Docker & Docker Compose for containerized development
Node.js 18+ for frontend development
Python 3.10+ for backend development
VS Code (recommended) with our workspace extensions

Development Setup¶

Clone the repository:

git clone https://github.com/your-username/fastapi_rbac.git
cd fastapi_rbac

Follow our comprehensive setup guide: 📖 Complete Setup Guide
Quick start with Docker:

docker-compose up -d
# Frontend: http://localhost:80
# Backend API: http://localhost:8000/docs

Install VS Code extensions:
Python, Black Formatter, isort, Flake8, Mypy
ESLint, Prettier
Docker, GitLens (recommended)

Development Guidelines¶

Project Organization¶

Feature-based development: Each feature should include backend API, frontend UI, tests, and documentation
API-first approach: Design API endpoints before implementing frontend
Documentation-driven: Update docs alongside code changes
Test-driven development: Write tests for new features

Branch Naming¶

Use descriptive branch names with prefixes:

feat/ - New features
fix/ - Bug fixes
docs/ - Documentation updates
test/ - Test improvements
refactor/ - Code refactoring
chore/ - Maintenance tasks

Commit Messages¶

Follow Conventional Commits:

type(scope): description

feat(auth): add password strength validation
fix(user): resolve email validation issue
docs(api): update authentication endpoints
test(user): add integration tests for user creation

Types: feat, fix, docs, style, refactor, test, chore

Code Standards¶

Backend (Python/FastAPI)¶

Code Quality Tools:

Black for code formatting
isort for import sorting
Flake8 for linting
Mypy for type checking

Run quality checks:

cd backend
black .
isort .
flake8 .
mypy . --exclude alembic

Key Conventions:

Use SQLModel's .exec() for all async DB queries (not .execute())
Follow PEP 8 style guidelines
Add type hints to all functions
Use Pydantic models for API schemas
Implement proper error handling with custom exceptions

Security Requirements:

Validate all input data
Use parameterized queries
Implement proper authentication checks
Follow OWASP security guidelines

Frontend (React/TypeScript)¶

Code Quality Tools:

Prettier for code formatting
ESLint for linting and import order

Run quality checks:

cd react-frontend
npx prettier --write .
npx eslint . --fix

Key Conventions:

Use TypeScript interfaces for all data models
Implement proper error handling
Follow React hooks best practices
Use Redux Toolkit for state management
Implement responsive design with Tailwind CSS

Testing Requirements¶

Backend Testing¶

Test Structure:

Unit tests: backend/test/unit/ - Test individual components
Integration tests: backend/test/integration/ - Test complete workflows
Test utilities: backend/test/factories/ and backend/test/fixtures/

Running Tests:

# All tests
python backend/test_runner.py all

# Unit tests only
python backend/test_runner.py unit

# Integration tests only
python backend/test_runner.py integration

# Specific test file
python backend/test_runner.py specific --path backend/test/unit/test_crud_user.py

Test Requirements:

All new features must include tests
Use factories for test data creation
Use API-driven flows for integration tests
Mock external services (email, Redis, etc.)
Achieve high test coverage (aim for 90%+)

Frontend Testing¶

Test Tools:

Vitest for unit testing
React Testing Library for component testing
MSW for API mocking

Running Tests:

cd react-frontend
npm test          # Run all tests
npm run test:ui   # Run with UI
npm run coverage  # Generate coverage report

Test Requirements:

Test all public component interfaces
Test user interactions and workflows
Mock API calls and external services
Test error states and edge cases

Test Quality Standards¶

Write descriptive test names that explain what is being tested
Use AAA pattern: Arrange, Act, Assert
Test edge cases and error conditions
Keep tests independent and idempotent
Use appropriate test data via factories
Document complex test scenarios

Submission Process¶

Pull Request Guidelines¶

Before Submitting:

Ensure all tests pass
Run code quality checks
Update documentation if needed
Check for breaking changes
Rebase on latest main branch

PR Description Template:

## Description

Brief description of changes

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing

- [ ] All existing tests pass
- [ ] New tests added for new functionality
- [ ] Manual testing completed

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or migration plan provided)

Review Process¶

Automated checks must pass (CI/CD pipeline)
Code review by at least one maintainer
Testing verification in review environment
Documentation review if applicable
Security review for security-related changes

Approval and Merge¶

PRs require approval from at least one maintainer
All conversations must be resolved
CI/CD pipeline must pass
Breaking changes require additional review and migration documentation

Release Process¶

Overview¶

This project follows a unified release notes and version tracking system. The docs/release-notes.md file serves as the single source of truth for all releases and major changes across the entire monorepo.

Versioning¶

We follow Semantic Versioning for our releases:

Major Version (X.0.0): Incompatible API changes or significant new features
Minor Version (0.X.0): Backward-compatible new features and enhancements
Patch Version (0.0.X): Backward-compatible bug fixes and minor improvements
Pre-release Versions: Suffixed with -alpha.N, -beta.N, or -rc.N (e.g., v1.0.0-beta.1)

Creating a New Release¶

Prepare the Release Notes:
Update docs/release-notes.md with the new version
Include the release date and summary of changes
Categorize changes into "New Features", "Bug Fixes", and "Breaking Changes"
Ensure the content is clear and understandable for users
Generate Draft Release Notes from Git History (optional):

Use Git commands to extract commit messages since the last tagged release:

git log <previous_tag>..<HEAD> --pretty=format:"- %s" > changelog.txt

Review, categorize, and edit the generated notes before adding to docs/release-notes.md
Update Version References:
Update any version references in the documentation
Ensure any version-specific instructions are updated
Create Git Tag:
Tag the release using the same version as in the release notes:
```
git tag -a vX.Y.Z -m "Release version X.Y.Z"
```
Push the tag to trigger the release workflow:
```
git push origin vX.Y.Z
```
Post-Release Actions:
Announce the release in appropriate channels
Monitor deployment and application health
Start planning for the next release cycle

Detailed Release Process¶

For a detailed step-by-step guide on creating releases, including Docker image publishing, see the Release Process Guide.

Community Guidelines¶

Code of Conduct¶

We are committed to providing a welcoming and inclusive environment for all contributors. We expect all community members to:

Be respectful and considerate in communications
Be collaborative and constructive in feedback
Be inclusive and welcoming to contributors of all backgrounds
Focus on what's best for the community and project
Show empathy towards other community members

Communication¶

GitHub Issues: Bug reports, feature requests, and discussions
Pull Requests: Code contributions and reviews
Documentation: Project guides and API references
Email: Security vulnerabilities should be reported privately

Inclusive Language¶

Use clear, descriptive language in code and documentation
Avoid technical jargon when simpler terms work
Be mindful of non-native English speakers
Choose inclusive terminology in variable names and comments

Getting Help¶

Documentation Resources¶

📖 Getting Started Guide - New developer onboarding
💻 Developer Setup - Complete environment setup
🧪 Testing Guide - Testing workflows and standards
🔧 Troubleshooting - Common issues and solutions
📋 API Reference - Complete API documentation

Getting Support¶

Check existing documentation first
Search GitHub issues for similar problems
Create a detailed issue if you can't find a solution
Join discussions on relevant GitHub issues
Ask questions in your pull request if you're unsure about implementation

Asking Good Questions¶

When asking for help, please include:

What you're trying to accomplish
What you've already tried
Relevant code snippets or error messages
Your development environment details
Steps to reproduce the issue

Recognition¶

Contributors¶

We believe in recognizing the valuable contributions of our community members:

Contributors are listed in our project documentation
Significant contributions are highlighted in release notes
Regular contributors may be invited to become project maintainers
All contributions are appreciated, from small typo fixes to major features

Types of Recognition¶

GitHub contributions graph shows your activity
Release notes mention significant contributions
Documentation credits for major doc improvements
Maintainer status for consistent, high-quality contributors

Additional Resources¶

Security¶

For security vulnerabilities, please email us privately rather than opening a public issue. We take security seriously and will respond promptly to verified vulnerabilities.

License¶

By contributing to this project, you agree that your contributions will be licensed under the same license as the project (MIT License).

Quick Reference¶

Task	Command	Documentation
Setup development	`docker-compose up -d`	Getting Started
Run backend tests	`python backend/test_runner.py all`	Testing Guide
Run frontend tests	`cd react-frontend && npm test`	Frontend Testing
Format code	`black . && prettier --write .`	Code Standards
Check quality	`flake8 . && eslint .`	Development Guidelines

Ready to contribute? 🚀 Start with our Getting Started Guide

Thank you for contributing to FastAPI RBAC! Your efforts help make this project better for everyone. 🙏