Workflow Guide

Development Workflow

This guide explains our development workflow, branching strategy, and collaboration processes.

Branching Strategy

We use a simplified Git Flow workflow:

Main Branches

main: Production-ready code, always stable
develop: Integration branch for features (if needed for complex releases)

Feature Branches

feature/feature-name: New features
fix/issue-description: Bug fixes
docs/documentation-update: Documentation changes
chore/maintenance-task: Maintenance tasks

Branch Naming Conventions

# Features
feature/add-market-indicators
feature/improve-error-handling

# Bug fixes
fix/rate-limit-calculation
fix/async-client-memory-leak

# Documentation
docs/api-reference-update
docs/getting-started-guide

# Maintenance
chore/update-dependencies
chore/refactor-logging

Development Process

1. Planning and Issue Creation

Check Existing Issues: Search for similar requests or bugs
Create Detailed Issues: Include requirements, expected behavior, and acceptance criteria
Get Alignment: Discuss approach for significant changes

2. Feature Development

Create Feature Branch

git checkout main
git pull origin main
git checkout -b feature/your-feature

Implement Changes
Follow coding standards
Add comprehensive tests
Update documentation
Commit frequently with clear messages

Keep Branch Updated

git fetch origin
git rebase origin/main

3. Code Quality Checks

Run all checks before pushing:

# Formatting
uv run ruff format fmp_data tests

# Linting
uv run ruff check fmp_data tests

# Type checking
uv run mypy fmp_data

# Tests (coverage runs in a dedicated CI job)
uv run pytest

# Documentation
uv run mkdocs build --strict

4. Pull Request Process

Push Feature Branch
```
git push origin feature/your-feature
```
Create Pull Request
Use descriptive title with conventional commit format
Fill out PR template completely
Add appropriate labels for semantic versioning
Request reviews from maintainers
Address Review Feedback
Make requested changes
Respond to comments
Keep discussion focused and constructive
Merge Process
Squash and merge for clean history
Delete feature branch after merge

Commit Message Guidelines

Conventional Commits Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Test additions or modifications
chore: Maintenance tasks

Examples

feat(client): add async support for all endpoints

fix(market): resolve rate limiting calculation bug

docs(api): update company client documentation

test(fundamental): add integration tests for financial statements

chore(deps): update httpx to latest version

Code Review Standards

Review Checklist

Functionality - [ ] Code works as intended - [ ] Edge cases are handled - [ ] Error handling is appropriate - [ ] Performance considerations addressed

Code Quality - [ ] Follows project coding standards - [ ] Type hints are complete and accurate - [ ] Documentation is clear and helpful - [ ] No code duplication or over-engineering

Testing - [ ] Adequate test coverage - [ ] Tests are meaningful and well-structured - [ ] Integration tests for API changes - [ ] Mock usage is appropriate

Documentation - [ ] Docstrings updated - [ ] API documentation reflects changes - [ ] Examples are provided where helpful - [ ] CHANGELOG updated if needed

Review Process

Automated Checks: GitHub Actions must pass
Peer Review: At least one maintainer approval required
Discussion: Address feedback constructively
Final Review: Ensure all concerns are resolved

Release Workflow

Semantic Versioning

We use automated semantic versioning based on PR labels:

major: Breaking changes (v1.0.0 → v2.0.0)
minor: New features (v1.0.0 → v1.1.0)
patch: Bug fixes (v1.0.0 → v1.0.1)

Release Process

PR Labeling: Add appropriate version labels to PRs
Automated Release: GitHub Actions handles versioning and publishing
Release Notes: Generated automatically from PR descriptions
Distribution: Published to PyPI automatically

Collaboration Guidelines

Communication

Be Clear: Use precise language in issues and PRs
Be Respectful: Maintain professional and welcoming tone
Be Helpful: Assist newcomers and share knowledge
Be Patient: Allow time for review and discussion

Issue Management

Triage: Label issues appropriately
Prioritization: Focus on critical bugs and high-impact features
Assignment: Assign issues to appropriate contributors
Tracking: Update progress and status regularly

Documentation Maintenance

Keep Current: Update docs with code changes
Examples: Provide practical usage examples
Clarity: Write for users at different experience levels
Organization: Maintain logical structure and navigation

Tools and Automation

GitHub Actions

CI/CD: Automated testing, linting, and type checking
Release: Automated versioning and PyPI publishing
Documentation: Automated docs building and deployment

Pre-commit Hooks

Code Formatting: Ruff format
Linting: Ruff
Type Checking: mypy
Security: bandit and pip-audit (as configured)

Development Dependencies

# Install all development dependencies
uv sync --group dev --group docs --group langchain --group mcp

# Update dependencies
uv sync --upgrade

# Add new dependency
uv add package-name
uv add --group dev package-name  # Development only

Troubleshooting Common Issues

Environment Setup

# Reset environment
rm -rf .venv
uv sync --group dev --group docs --group langchain --group mcp

# Clear cache
uv cache clean

Git Issues

# Sync with main
git fetch origin
git rebase origin/main

# Fix merge conflicts
git rebase --continue

# Reset branch
git reset --hard origin/main

Testing Issues

# Run specific tests
uv run pytest tests/unit/test_client.py -v

# Debug failing tests
uv run pytest tests/unit/test_client.py::test_function_name -s

# Update test snapshots
uv run pytest --snapshot-update

Getting Help

GitHub Discussions: Ask questions and share ideas
Discord/Slack: Real-time chat (if available)
Documentation: Check existing guides and API docs
Issues: Report bugs or request clarification