Contributing

Welcome Contributors!

Thank you for your interest in contributing to VidaPlus API! This guide will help you set up your development environment and understand the contribution workflow.

Development Environment Setup

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.13+

The project requires Python 3.13.2 or higher

Poetry

Version 2.1.2 for dependency management

Git

For version control and collaboration

PostgreSQL

Optional for local database (SQLite works for development)

Installing Python

The project uses Python 3.13.2. We recommend using pyenv for Python version management:

# Install pyenv (if not already installed)
curl https://pyenv.run | bash

# Install Python 3.13.2
pyenv install 3.13.2

# Set local Python version for the project
cd vidaplus-api
pyenv local 3.13.2

Verify the installation:

python --version
# Output: Python 3.13.2

Installing Poetry

Install Poetry 2.1.2 using pipx:

# Install pipx if not already installed
python -m pip install --user pipx
python -m pipx ensurepath

# Install Poetry
pipx install poetry==2.1.2

# Install Poetry shell plugin
pipx inject poetry poetry-plugin-shell

Verify the installation:

poetry --version
# Output: Poetry (version 2.1.2)

Getting Started

Fork the Repository

Fork the VidaPlus API repository to your GitHub account:

Go to the VidaPlus repository
Click the “Fork” button in the top-right corner
Select your GitHub account as the destination

Clone Your Fork

Clone your forked repository to your local machine:

git clone https://github.com/YOUR_USERNAME/vidaplus-api.git
cd vidaplus-api

Add the original repository as upstream:

git remote add upstream https://github.com/lrauane/vidaplus-api.git

Install Dependencies

Install all project dependencies using Poetry:

poetry install

This installs both production and development dependencies defined in pyproject.toml.

Activate Virtual Environment

Activate the Poetry-managed virtual environment:

poetry shell

Your terminal prompt should change to indicate you’re in the virtual environment.

Set Up Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env with your configuration:

DATABASE_URL=sqlite:///./vidaplus_dev.db
SECRET_KEY=your-secret-key-for-development
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

Run Database Migrations

Set up the database schema:

alembic upgrade head

Verify Installation

Run the development server to verify everything works:

task run

Visit http://localhost:8000/docs to see the API documentation.

Development Workflow

Creating a Feature Branch

Always create a new branch for your changes:

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ - New features (e.g., feature/add-exam-scheduling)
fix/ - Bug fixes (e.g., fix/patient-validation-error)
docs/ - Documentation updates (e.g., docs/update-api-guide)
refactor/ - Code refactoring (e.g., refactor/simplify-auth-logic)

Making Changes

Write your code following the project’s code standards
Add tests for new functionality
Run linting and formatting:

# Check code style
task lint

# Auto-format code
task format

Run tests to ensure everything works:

task test

Committing Changes

Write clear, descriptive commit messages following conventional commits:

git add .
git commit -m "feat: add exam scheduling endpoint"

Commit message format:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
style: - Code style changes (formatting, etc.)
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Maintenance tasks

Examples:

git commit -m "feat: add leito availability check endpoint"
git commit -m "fix: resolve patient CPF validation issue"
git commit -m "docs: update authentication guide"
git commit -m "test: add tests for consulta endpoints"

Submitting a Pull Request

Push Your Branch

Push your feature branch to your fork:

git push origin feature/your-feature-name

Create Pull Request

Go to your fork on GitHub
Click “Compare & pull request”
Select the base repository and branch (usually main)
Fill out the PR template with:
- Description of changes
- Related issue numbers
- Screenshots (if applicable)
- Testing performed

Address Review Feedback

After submitting, maintainers may request changes:

Make the requested changes locally
Commit the changes
Push to the same branch:

git add .
git commit -m "fix: address PR feedback"
git push origin feature/your-feature-name

The PR will automatically update.

Code Standards

Code Style

VidaPlus API uses Ruff for linting and formatting. The configuration is in pyproject.toml:

[tool.ruff]
line-length = 79
extend-exclude = ['migrations']

[tool.ruff.format]
preview = true
quote-style = 'single'

Key rules:

Maximum line length: 79 characters
Use single quotes for strings
Migration files are excluded from linting

Running Code Quality Checks

task lint

Testing Requirements

All new features and bug fixes must include tests.

Test coverage guidelines:

Aim for 80%+ code coverage
Test happy paths and error cases
Test authentication and authorization
Test database operations

Example test structure:

from http import HTTPStatus

def test_create_exam(client, token_profissional):
    """Test creating a new exam request."""
    response = client.post(
        '/exame/',
        json={
            'tipo_exame': 'HEMOGRAMA',
            'paciente_id': 1,
            'data_solicitacao': '2025-05-20',
        },
        headers={'Authorization': f'Bearer {token_profissional}'},
    )
    
    assert response.status_code == HTTPStatus.CREATED
    assert response.json()['tipo_exame'] == 'HEMOGRAMA'

Documentation Standards

When adding new features:

Add docstrings to functions and classes:

def create_exam(
    exam: ExameSchema,
    session: Session,
    current_user: User
) -> Exame:
    """
    Create a new exam request.
    
    Args:
        exam: Exam data schema
        session: Database session
        current_user: Authenticated user
    
    Returns:
        Created exam instance
    
    Raises:
        HTTPException: If user lacks permissions
    """
    ...

Update API documentation if adding new endpoints
Update README.md if changing setup procedures

Available Tasks

The project uses taskipy for common development tasks. View all tasks:

task --list

Available tasks:

Task	Command	Description
`task lint`	`ruff check`	Check code for style issues
`task format`	`ruff check --fix && ruff format`	Auto-format code
`task run`	`fastapi dev vidaplus/app.py`	Run development server
`task test`	`pytest -s -x --cov=vidaplus -vv`	Run tests with coverage

The test task automatically:

Runs linting before tests (pre_test)
Executes pytest with coverage
Generates HTML coverage report (post_test)

Project Structure

Understanding the project structure helps you navigate the codebase:

vidaplus-api/
├── vidaplus/              # Main application package
│   ├── api/              # API endpoints
│   │   └── endpoints/    # Route handlers
│   ├── models/           # Database models
│   ├── schemas/          # Pydantic schemas
│   ├── utils/            # Utility functions
│   ├── app.py           # FastAPI application
│   ├── database.py      # Database configuration
│   ├── security.py      # Authentication logic
│   └── settings.py      # Environment settings
├── migrations/           # Alembic migrations
│   ├── versions/        # Migration files
│   └── env.py          # Alembic environment
├── tests/               # Test suite
│   ├── conftest.py     # Shared fixtures
│   └── test_*.py       # Test modules
├── Dockerfile           # Docker configuration
├── alembic.ini         # Alembic configuration
├── pyproject.toml      # Poetry dependencies & config
└── README.md           # Project documentation

Common Contribution Types

Adding a New Endpoint

Create Schema

Add Pydantic schemas in vidaplus/schemas/:

from pydantic import BaseModel

class ExameCreate(BaseModel):
    tipo_exame: str
    paciente_id: int
    data_solicitacao: str

Create Database Model

If needed, add model in vidaplus/models/models.py and create migration:

alembic revision --autogenerate -m "add exame table"
alembic upgrade head

Create Endpoint

Add route handler in vidaplus/api/endpoints/:

@router.post('/', status_code=HTTPStatus.CREATED)
def create_exam(
    exam: ExameCreate,
    session: Session = Depends(get_session),
    current_user: User = Depends(get_current_user)
):
    # Implementation
    ...

Add Tests

Create tests in tests/test_exame.py:

def test_create_exam(client, token_profissional):
    response = client.post('/exame/', ...)
    assert response.status_code == HTTPStatus.CREATED

Run Tests

Verify everything works:

task test

Fixing a Bug

Write a Failing Test

First, create a test that reproduces the bug:

def test_patient_cpf_validation():
    # This test should fail before the fix
    ...

Fix the Bug

Make the minimum changes needed to fix the issue.

Verify Tests Pass

Run tests to ensure the fix works:

task test

Add Regression Test

Ensure the test remains in the suite to prevent regressions.

Getting Help

If you need assistance:

GitHub Issues: Search existing issues or create a new one
Pull Request Comments: Ask questions directly in your PR
Documentation: Check the API documentation

Code of Conduct

When contributing, please:

Be respectful and inclusive
Provide constructive feedback
Focus on the code, not the person
Help create a welcoming environment for all contributors

Recognition

Contributors are recognized in:

GitHub contributor list
Project documentation
Release notes

Maintainer

VidaPlus API is maintained by Rauane Lima.

Next Steps

Docker Deployment

Learn how to deploy with Docker

Testing Guide

Deep dive into the testing framework

Database Migrations

Learn about Alembic migrations

API Reference

Explore the complete API documentation

Get Started

Core Concepts

Guides

Welcome Contributors!

Development Environment Setup

Prerequisites

Python 3.13+

Poetry

Git

PostgreSQL

Installing Python

Installing Poetry

Getting Started

Development Workflow

Creating a Feature Branch

Making Changes

Committing Changes

Submitting a Pull Request

Code Standards

Code Style

Running Code Quality Checks

Testing Requirements

Documentation Standards

Available Tasks

Project Structure

Common Contribution Types

Adding a New Endpoint

Fixing a Bug

Getting Help

Code of Conduct

Recognition

Maintainer

Next Steps

Docker Deployment

Testing Guide

Database Migrations

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Welcome Contributors!

​Development Environment Setup

​Prerequisites

Python 3.13+

Poetry

Git

PostgreSQL

​Installing Python

​Installing Poetry

​Getting Started

​Development Workflow

​Creating a Feature Branch

​Making Changes

​Committing Changes

​Submitting a Pull Request

​Code Standards

​Code Style

​Running Code Quality Checks

​Testing Requirements

​Documentation Standards

​Available Tasks

​Project Structure

​Common Contribution Types

​Adding a New Endpoint

​Fixing a Bug

​Getting Help

​Code of Conduct

​Recognition

​Maintainer

​Next Steps

Docker Deployment

Testing Guide

Database Migrations

API Reference

Build docs developers (and LLMs) love

Welcome Contributors!

Development Environment Setup

Prerequisites

Installing Python

Installing Poetry

Getting Started

Development Workflow

Creating a Feature Branch

Making Changes

Committing Changes

Submitting a Pull Request

Code Standards

Code Style

Running Code Quality Checks

Testing Requirements

Documentation Standards

Available Tasks

Project Structure

Common Contribution Types

Adding a New Endpoint

Fixing a Bug

Getting Help

Code of Conduct

Recognition

Maintainer

Next Steps