Skip to content

Contributing Guidelines

Thank you for your interest in contributing to the UBU Digital Finance Solution backend. This document provides guidelines and instructions for contributing to the project.

Code of Conduct

We expect all contributors to adhere to our code of conduct, which promotes a respectful and inclusive environment for everyone.

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone <your-fork-url>
  3. Create a new branch for your feature or bugfix: git checkout -b feature/your-feature-name
  4. Make your changes
  5. Run tests to ensure your changes don't break existing functionality
  6. Commit your changes with descriptive commit messages
  7. Push your branch to your fork
  8. Submit a pull request to the main repository

Development Workflow

Setting Up Your Development Environment

Follow the instructions in the Setup Guide to set up your development environment.

Branching Strategy

  • main: The production branch, containing stable code
  • develop: The development branch, containing code for the next release
  • feature/*: Feature branches for new features
  • bugfix/*: Bugfix branches for bug fixes
  • hotfix/*: Hotfix branches for critical production fixes

Commit Messages

Write clear, concise commit messages that describe the changes you've made. Follow these guidelines:

  • Use the present tense ("Add feature" not "Added feature")
  • Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit the first line to 72 characters or less
  • Reference issues and pull requests liberally after the first line

Example: 

Add two-factor authentication for user login

- Implement OTP generation and verification
- Add email sending for OTP delivery
- Update authentication flow to include OTP step

Fixes #123

Pull Request Process

  1. Ensure your code follows the project's coding standards
  2. Update the documentation to reflect any changes
  3. Add or update tests as necessary
  4. Make sure all tests pass
  5. Get at least one code review from a maintainer
  6. Once approved, a maintainer will merge your pull request

Coding Standards

Python Style Guide

We follow the PEP 8 style guide for Python code. Additionally:

  • Use 4 spaces for indentation (not tabs)
  • Use docstrings for all public modules, functions, classes, and methods
  • Keep line length to a maximum of 88 characters
  • Use type hints where appropriate
  • Use f-strings for string formatting

FastAPI Best Practices

  • Use Pydantic models for request and response validation
  • Use dependency injection for common functionality
  • Document API endpoints with appropriate descriptions and examples
  • Use proper HTTP status codes and error responses
  • Implement proper error handling

Database Practices

  • Use SQLAlchemy models for database operations
  • Create Alembic migrations for database changes
  • Use async database operations where appropriate
  • Follow naming conventions for database objects

Testing

We use pytest for testing. All new features should include tests, and all tests must pass before a pull request can be merged.

Running Tests

pytest

Test Coverage

We aim for high test coverage. You can check the test coverage by running:

pytest --cov=app

Documentation

All new features should be documented. We use MkDocs for our documentation.

Building Documentation

mkdocs build

Serving Documentation Locally

mkdocs serve

Feature Requests and Bug Reports

If you have a feature request or have found a bug, please create an issue in the repository. Please provide as much detail as possible, including:

  • A clear and descriptive title
  • A detailed description of the feature or bug
  • Steps to reproduce the bug (if applicable)
  • Expected behavior
  • Actual behavior
  • Screenshots (if applicable)
  • Environment information (OS, browser, etc.)

Code Review Process

All pull requests will be reviewed by at least one maintainer. The review process includes:

  1. Checking that the code follows the project's coding standards
  2. Verifying that the code works as expected
  3. Ensuring that the code is well-tested
  4. Reviewing the documentation

Continuous Integration

We use continuous integration to automatically run tests and linting on all pull requests. All CI checks must pass before a pull request can be merged.

Versioning

We follow Semantic Versioning for versioning the project.

License

By contributing to this project, you agree that your contributions will be licensed under the project's license.