Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The contributing guidelines for flext-target-oracle provide a structured framework for developers to participate in the project's evolution. This project is a Singer target implementation for Oracle Database loading, built on the FLEXT ecosystem patterns. The guidelines ensure that all contributions—whether features, bug fixes, or documentation—maintain the project's standards for type safety, performance, and reliability.
These guidelines cover the entire development lifecycle, from initial environment setup and architectural principles to testing requirements and the pull request process. Developers are expected to follow specific design patterns such as Railway-Oriented Programming (ROP) and clean architecture to ensure consistency across the FLEXT suite.
Sources: CONTRIBUTING.md:46-77, README.md:8-12
Development Environment Setup
Contributing requires a specific environment to handle the Python 3.13 requirement and the Oracle database dependencies. The project utilizes Poetry for dependency management and Docker to host the Oracle XE instance required for integration testing.
Prerequisites and Installation
Contributors must have Git, Python 3.13+, Docker, and Poetry installed. The following workflow initializes the environment:
- Clone the Repository: `git clone https://github.com/flext-sh/flext-target-oracle.git%60
- Install Dependencies: Use
make dev-setuporpoetry install --all-extras. - Start Database: Use
make oracle-startto launch the Oracle container. - Verify Setup: Run
make test-unitto confirm the environment is functional.
Sources: CONTRIBUTING.md:46-77, pyproject.toml:35-42
Development Workflow
The following diagram illustrates the standard developer onboarding and environment initialization flow:
The diagram shows the sequential steps required to move from a fresh clone to a development-ready state.
Sources: CONTRIBUTING.md:58-77, tests/README.md:120-130
Architecture and Design Principles
The project follows a modular architecture that separates Singer interface logic from core database operations.
Key Components
| Component | File Path | Responsibility |
|---|---|---|
| Target Class | src/flext_target_oracle/target.py | Implements FlextSingerUnifiedInterface, routes messages, and manages state. |
| Loader Class | src/flext_target_oracle/loader.py | Handles DDL/DML, schema flattening, and type mapping via flext-db-oracle. |
| Settings | src/flext_target_oracle/settings.py | Defines Pydantic models for configuration and domain validation rules. |
| Exceptions | src/flext_target_oracle/exceptions.py | Provides a custom hierarchy for Oracle-specific errors. |
Sources: CONTRIBUTING.md:120-136
Core Principles
All code contributions must adhere to the following design patterns:
- Railway-Oriented Programming (ROP): Using the
rpattern for error handling to avoid complex try-except blocks. - Dependency Injection: Behavior should be configuration-driven.
- Clean Architecture: Maintaining a strict separation of concerns between the target interface and the loader logic.
- Type Safety: Mandatory use of strict type hints throughout the codebase.
- Database Isolation: Never generate SQL directly in the target; use
FlextDbOracleApi.
Sources: CONTRIBUTING.md:138-145, examples/README.md:73-77
Testing Standards
Testing is a critical gate for all contributions. The project employs a tiered testing strategy to balance speed and accuracy.
Test Categories
- Unit Tests (
tests/unit/): Fast tests using mocked dependencies. They must not require a running database. - Integration Tests (
tests/integration/): Require a real Oracle database to verify DDL/DML operations. - End-to-End Tests (
tests/e2e/): Validate complete Singer workflows and data pipelines. - Performance Tests (
tests/performance/): Benchmark bulk loading and optimization.
Sources: CONTRIBUTING.md:82-90, tests/README.md:37-47
Automated Test Management
The project uses pytest and a custom make contract. Integration tests automatically manage the Oracle XE container lifecycle.
The sequence diagram demonstrates how integration tests trigger automated Docker container management to ensure a valid database environment.
Sources: tests/README.md:65-75
Coding and Documentation Style
Consistency in code style is enforced through automated quality gates.
Formatting and Linting
The project uses the following tools as defined in pyproject.toml:
- Black & Ruff: For formatting and linting.
- Mypy & Pyright: For strict type checking.
- Isort: For import organization.
- Pre-commit Hooks: Mandatory for local development to catch issues before submission.
Sources: CONTRIBUTING.md:103-118, pyproject.toml:440-480
Documentation Requirements
- Google-style Docstrings: Required for all public APIs and methods.
- Type Annotations: Must be complete (no implicit
Any). - Examples: New features must be accompanied by an update to the
examples/directory.
Sources: CONTRIBUTING.md:156-170, examples/README.md:104-110
Pull Request Process
To ensure high quality, the submission process follows a strict checklist.
Submitting Changes
- Branching: Use prefixes like
feature/,fix/,docs/, orrefactor/. - Commits: Follow Conventional Commits (e.g.,
feat: add bulk merge support). - PR Checklist:
- Tests pass locally (
make test). - Code is formatted and passes type checking (
make check). - Documentation and Examples are updated.
- Changelog entry added if applicable.
- Tests pass locally (
Sources: CONTRIBUTING.md:188-210
Quality Gates
The CI/CD pipeline enforces minimum coverage thresholds. A minimum code coverage of 80% is required for all PRs.
Sources: tests/README.md:100-103, pyproject.toml:130-135
Summary
Contributing to FLEXT Target Oracle requires adherence to strict architectural patterns, particularly Railway-Oriented Programming and type safety. By utilizing the provided Docker-based testing environment and following the make quality gates, contributors ensure that the Oracle loading engine remains robust, performant, and maintainable.
Sources: CONTRIBUTING.md:225-230