Development Practices & Guidelines

Comprehensive development guidelines for building high-quality, maintainable code in an open startup environment

Note from CTO: These guidelines ensure consistency across our codebase while maintaining the flexibility needed for rapid iteration. They're designed to scale with our team and help new contributors understand our standards.

🎯 Code Quality Standards

Core Principles

Readability First: Code should be self-documenting and easy to understand
Consistency: Follow established patterns and conventions
Maintainability: Write code that's easy to modify and extend
Performance: Optimize for user experience, not premature optimization
Security: Security by design, not as an afterthought

Code Review Checklist

Every PR should address these points:

Functionality: Does the code do what it's supposed to do?
Readability: Is the code easy to understand?
Testing: Are there appropriate tests?
Documentation: Is the code self-documenting or well-commented?
Performance: Are there obvious performance issues?
Security: Are there security vulnerabilities?
Accessibility: Does it work for all users?

🏗️ Architecture Guidelines

System Design Principles

1. Modularity

Single Responsibility: Each module/class has one clear purpose
Loose Coupling: Minimize dependencies between modules
High Cohesion: Related functionality stays together

2. Scalability

Horizontal Scaling: Design for multiple instances
Database Design: Plan for growth from day one
Caching Strategy: Implement caching where it makes sense

3. Maintainability

Clear Interfaces: Well-defined APIs and contracts
Configuration: Externalize configuration, not hardcoded values
Logging: Comprehensive logging for debugging and monitoring

Technology Stack Decisions

Frontend

Framework: React with TypeScript
Styling: Tailwind CSS for rapid development
State Management: React Context + hooks for simplicity
Testing: Jest + React Testing Library

Backend

Language: Python (FastAPI) for API development
Database: PostgreSQL with Prisma/ORM
Authentication: JWT with secure session management
API Design: RESTful with OpenAPI documentation

Infrastructure

Hosting: Cloud providers (Vercel, Railway, Render)
CI/CD: GitHub Actions
Monitoring: Built-in platform monitoring + custom metrics
Security: HTTPS everywhere, security headers, rate limiting

📝 Coding Standards

General Guidelines

Naming Conventions

Variables/Functions: camelCase for JavaScript/TypeScript, snake_case for Python
Constants: UPPER_SNAKE_CASE
Classes: PascalCase
Files: kebab-case for multi-word files
Descriptive Names: Avoid abbreviations, be explicit

Error Handling

Always handle errors explicitly. Silent failures make debugging nearly impossible and can lead to data corruption or security issues.

Frontend Standards

React Best Practices

Functional Components: Use hooks and functional components
Custom Hooks: Extract reusable logic into custom hooks
Props Interface: Always define TypeScript interfaces for props
State Management: Keep state as local as possible, lift when necessary

CSS/Styling Guidelines

Utility-First: Use Tailwind CSS utilities when possible
Custom CSS: Only when Tailwind doesn't provide what you need
Responsive Design: Mobile-first approach
Accessibility: Proper contrast ratios, focus states, screen reader support

Backend Standards

API Design

RESTful: Follow REST conventions
Consistent Response Format: Standardize API responses
Error Handling: Proper HTTP status codes and error messages
Validation: Input validation on all endpoints
Rate Limiting: Protect against abuse

Database Practices

Migrations: Always use migrations for schema changes
Indexing: Add indexes for frequently queried fields
Transactions: Use transactions for related operations
Connection Pooling: Implement proper connection management

🧪 Testing Standards

Testing Strategy

Test Types & Coverage

Unit Tests: 80%+ coverage for business logic
Integration Tests: API endpoints, database operations
E2E Tests: Critical user journeys
Performance Tests: Load testing for key features

Testing Best Practices

WET, not DRY: Tests should be explicit and easy to read
Fixed Dates: Use specific dates (e.g., 2022-01-05) rather than dynamic dates
Factory Defaults: Keep factory defaults to a minimum
No Hardcoded IDs: Never hardcode auto-generated IDs in tests

🔒 Security Guidelines

Authentication & Authorization

JWT Tokens: Secure token storage and rotation
Role-Based Access: Implement proper RBAC
Session Management: Secure session handling
Password Security: Strong hashing, complexity requirements

Data Protection

Input Validation: Sanitize all user inputs
SQL Injection: Use parameterized queries
XSS Prevention: Escape user-generated content
CSRF Protection: Implement CSRF tokens

API Security

Rate Limiting: Prevent abuse and DDoS
HTTPS Only: No HTTP in production
Security Headers: Implement security headers
CORS Policy: Restrict cross-origin requests

📚 Documentation Requirements

Code Documentation

README: Every repository needs a comprehensive README
API Documentation: OpenAPI/Swagger for all endpoints
Inline Comments: Explain complex logic, not obvious code
Architecture Decisions: Document major technical decisions

README Template

Every project should include:

Brief description of what the project does
Key features list
Prerequisites and installation steps
Development commands (test, lint, build)
Contributing guidelines
License information

🚀 Performance Guidelines

Frontend Performance

Code Splitting: Lazy load routes and components
Image Optimization: Use appropriate formats and sizes
Bundle Analysis: Monitor bundle size and optimize
Caching: Implement proper caching strategies

Backend Performance

Database Queries: Optimize queries, use indexes
Caching: Redis for frequently accessed data
Async Operations: Use async/await for I/O operations
Connection Pooling: Manage database connections efficiently

🔄 Continuous Integration

CI/CD Pipeline

Automated Testing: Run tests on every PR
Code Quality: Linting, formatting, security scanning
Build Verification: Ensure code builds successfully
Deployment: Automated deployment to staging/production

Pre-commit Hooks

Set up pre-commit hooks for:

Code linting and formatting
Commit message validation
Test execution
Security scanning

🤝 Open Source Practices

Contributing Guidelines

Issue Templates: Use standardized issue templates
PR Templates: Include checklist and description
Code of Conduct: Enforce community standards
Contributor Recognition: Acknowledge contributions

Community Engagement

Documentation: Keep docs up-to-date
Examples: Provide working examples
Feedback: Actively seek and incorporate feedback
Transparency: Share progress and challenges

📋 Quality Gates

Before Merging

All tests pass
Code review completed
Documentation updated
Security scan passed
Performance benchmarks met
Accessibility requirements satisfied

Before Deploying

Staging environment tested
Rollback plan ready
Monitoring configured
Team notified
Post-deployment checklist ready

🔄 Development Process

Why We Document Our Development Process

Readable, consistent code is important for development as it allows for efficient maintenance and eases the introduction of new features
Faster, more efficient processes through standardized workflows
Simpler workflows that improve the development experience
Easier onboarding and training for new contributors
Boosted output and productivity through clear processes
Lower costs by minimizing errors and rework
Streamlined compliance and easier evidence gathering for audits

Who This Process Applies To

Everyone who has access to our codebase
Core team members have increased privileges for critical, time-sensitive fixes
Community contributors follow the standard process
All team members are responsible for maintaining process integrity

THINGS TO NEVER DO

NEVER rebase - it rewrites history and makes debugging difficult
NEVER squash - preserve commit history for context
NEVER merge main to your branch unless absolutely necessary
NEVER force push unless entirely necessary

🚀 Our Development Process

1. Issue Management

When a PR is open, all permanent communication lives in GitHub on the PR
Once a PR is merged, all permanent communication lives on the GitHub issue
Every PR must follow proper naming conventions
Every PR must have appropriate labels and approvals

2. Branch Naming Convention

Format: {your_name}/MEET-XXXX_cool_thing
Example: john/meet-1234_user_authentication
For non-issue work: {your_name}/meet-0_cool-thing

3. PR Requirements

Every PR must have:

Proper naming convention (links to GitHub issue)
3 PR review approvals (at least 2 from developers)
Required labels:
- Passed Code Review
- Either: Passed QA or No QA Needed
- Design Approved (if applicable)

4. Review Process

Code Review: At least 2 developer approvals required
QA Review: At least 1 QA approval if Ready for QA label is present
Design Review: At least 1 design approval if Needs Design Approval label is present
All communication stays in GitHub on the PR

5. Local Validation

Every PR must pass through local validation before merging
QA team members approve PRs as reviewers
Evidence of testing must be provided in approval comments
Anyone on the team can do validation (not just QA)

🌿 Branching Strategy

Main Branch

Represents the latest development codebase
Feature branches are merged here once completed
Merges trigger automated tests, build process, and deployment to staging

Release Branch

Used for preparing releases to production
Only bugfixes for the upcoming release are merged here
Merges trigger automated tests and deployment to UAT environment

Production Branch

Represents the deployed code
Hotfixes are generated from this branch
Production deployments are manually triggered

Hotfix Process

If issues are found in release branch, create PR against release branch
For production issues, create branch from production branch
Coordinate with team for manual deployment
Ensure fixes are merged into relevant downstream branches

🏷️ Label Management

QA Labels

No QA Needed - team agrees no formal QA needed
Needs Design Approval - significant frontend changes
QA on Staging - test on staging environment
QA on UAT - test on UAT environment
QA on Production - test on production environment

Process Labels

Ready for Code Review - PR ready for developer review
Ready for QA - PR ready for QA validation
Passed Code Review - code review completed
Passed QA - QA validation completed
Design Approved - design review completed
Do Not Merge - blocks merging

🔍 Issue Selection & Responsibility

Choosing Issues

Pick from the top of the backlog (highest priority)
Choose something you feel comfortable with, but don't be afraid to learn
If something is missing or unclear, reach out to your team lead

Issue Ownership

You are responsible for seeing the issue through to deployment
Your issue is not done unless it's working correctly in production
This includes understanding requirements, coding, testing, infrastructure, and user satisfaction

Team Delivery

The team must deliver every issue in the sprint
Focus on delivering committed work even if it means helping others
If you run out of work, help with code reviews, testing, documentation, or proof of concepts

🧪 Testing & Validation

Local Validation Process

All PRs must go through local validation before merging
Anyone can do validation except the original developer or code approvers
Document results in PR approval comments
Use "Request Changes" for blocking issues

Post-Merge Validation

Additional validation is done after PR is merged
Team responsibility - anyone can validate except original developer
Document in GitHub issues with environment, validation description, and evidence

Defect Handling

All communication stays in GitHub during PR phase
Use "Request Changes" for blocking issues
Engage directly with developer via Slack for resolution
Move issue back to "In Progress" if significant changes needed

🚫 Exceptions to Local Validation

When to Skip Local Validation

Testing with external vendors requires integrated environment
Infrastructure changes that can't be tested locally
Third-party integrations that require staging environment

Exception Labels

QA on Staging - test for first time on staging
QA on UAT - test for first time on UAT
QA on Production - test for first time on production

Use these labels sparingly - local validation exists for good reasons.

🐛 Bug Priority Guidelines

Critical Priority

System crashes or hangs
Security vulnerabilities
Data loss or corruption
Critical functionality broken
Compliance violations

High Priority

Major functionality broken
Major performance or usability issues
Significant data integrity issues
Issues blocking further testing or development
Issues affecting significant portion of users

Medium Priority

Minor functionality broken
Minor performance or usability issues
Minor data integrity issues
Issues not blocking further work
Issues affecting small portion of users

Low Priority

Cosmetic or aesthetic issues
Minor documentation or formatting issues
Issues with minimal impact
Issues affecting only a few users
Issues with easy workarounds

📝 Naming Conventions

Repository Organization

Each service has its own directory
Always start backend libraries with meetball_ to prevent conflicts
Libraries are named to reflect their purpose
Tests are found under tests/ folder for each library

Naming Rules

Avoid acronyms unless extremely common
No version numbers (old/new, type 1/2/3) unless temporary or from vendor
No team names in filenames, messages, or logging
Limit proprietary product names in feature naming
Use "Meetball" not "MeetBall", "MeetBall", or "MEETBALL"
Lowercase preferred for comments and log messages
Snake case for fields and identifiers
Literal names that reflect what they represent
No cute or clever names for internal items

📊 Logging Best Practices

Logging Guidelines

Log early, log often - easier to turn down than add later
Log context-specific information including logical conditions and variables
DO NOT simply log function inputs
Log unusual or complicated cases
Use lowercase for log messages unless drawing attention
Configure logger with logging.getLogger(__name__)
DO NOT use logging.basicConfig in importable modules

🚫 Prohibited Practices

Feature Branches

Do not use long-lived feature branches
Results in messy merge conflicts
Possibility of introducing large numbers of bugs
Lack of incremental delivery

History Rewriting

Never rebase, squash, or force push unless absolutely necessary
Preserve commit history for debugging and context
Tools like git bisect become unusable with rewritten history

These guidelines are living documents. As we learn and grow, we'll update them to reflect our evolving best practices. Your feedback and suggestions are always welcome!

Last Updated: September 9, 2025 by @drhinca: Adrián Bado Chinca

Edit this page Report an issue