Contribution & Developer Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
- docusaurus/platform_versioned_docs/version-2.1/contributing-to-airbyte/writing-docs.md
- docusaurus/platform_versioned_docs/version-2.1/connector-development/ux-handbook.md
- docusaurus/platform_versioned_docs/version-2.0/contributing-to-airbyte/writing-docs.md
- docusaurus/platform_versioned_docs/version-1.7/contributing-to-airbyte/README.md
- docusaurus/platform_versioned_docs/version-1.8/contributing-to-airbyte/writing-docs.md
Airbyte welcomes contributions to its open-source data integration platform, including code for connectors, platform enhancements, and documentation. The project emphasizes trust, reliability, and security as core infrastructure components, requiring all contributions to adhere to high standards of data integrity and quality.
Contributors are expected to follow a structured workflow involving forking the repository, creating feature-specific branches, and submitting pull requests for review. Guidelines cover diverse areas such as Java/Python connector development, documentation via Docusaurus, and maintaining specialized UX standards for connector configurations.
Code Contribution Workflow
The standard process for contributing code to the Airbyte repository follows a Git-based workflow. Most issues available for external contributors are labeled as good first issue or help-welcome.
Standard Workflow Steps
The following diagram illustrates the lifecycle of a code contribution from the initial fork to the final merge.
The diagram shows the sequential steps required for code submission, emphasizing the importance of linking existing issues and passing CI tests.
Sources: version-1.7/contributing-to-airbyte/README.md:37-51
Contribution Areas
Airbyte specifically seeks contributions in the following technical domains:
- API Connectors: Bug fixes and features for existing sources or new sources using the Connector Builder.
- Database Sources: Enhancements for Postgres, MySQL, and MSSQL.
- Destinations: Fixes for BigQuery, Snowflake, Redshift, S3, and Postgres.
- Platform: Helm Chart features and general platform bug fixes.
Sources: version-1.7/contributing-to-airbyte/README.md:23-31
Documentation Guidelines
Airbyte's documentation is built using Docusaurus and hosted within the main repository. It is written in Markdown and follows the Google Developer Documentation Style Guide.
Documentation Architecture
The documentation site is organized into multiple instances to manage versioning and content types effectively.
| Instance | Versioned | Purpose |
|---|---|---|
| Home | No | Main landing page |
| Platform | Yes | Core platform functionality and API |
| Connectors | No | Documentation for specific source/destination connectors |
| Release Notes | No | Changelogs and update history |
Sources: version-1.8/contributing-to-airbyte/writing-docs.md:144-152
Writing Standards
Contributors must utilize specific templates based on the purpose of the document:
- Concept: Explains context or product background.
- How-to: Numbered steps for a single task.
- Tutorial: Hands-on learning projects.
- Troubleshooting: Resolving common user issues.
- Reference: In-depth technical details.
Sources: version-1.6/contributing-to-airbyte/writing-docs.md:120-131
Automated Linting
To maintain high quality, Airbyte employs two primary linters:
- Vale: Checks for style, grammar, and adherence to the Airbyte voice.
- MarkDownLint: Ensures structural integrity and proper Markdown syntax.
These tools run automatically in CI via the Reviewdog workflow on pull requests.
Sources: version-2.0/contributing-to-airbyte/writing-docs.md:290-302
Connector UX & Architecture Principles
Connector development is governed by a "UX Handbook" that prioritizes the hierarchy of user needs: Security, Data Integrity, and Reliability.
The diagram represents the hierarchy of needs for Airbyte infrastructure, where security and integrity form the foundational requirements.
Sources: version-2.1/connector-development/ux-handbook.md:60-70
Key Design Patterns
- ELT over ETL: Airbyte favors Extract-Load-Transform. Data should be loaded into destinations as close to the original source format as possible to avoid Airbyte becoming a development bottleneck.
- Configuration Minimization: Developers should avoid exposing implementation details (like retry counts) in the
spec.json. Sensible defaults should be used to minimize user friction. - Fail Fast: Input configurations should use JSON Schema "pattern" keywords to validate inputs immediately and provide actionable error messages.
Sources: version-2.1/connector-development/ux-handbook.md:183-205, version-2.1/connector-development/ux-handbook.md:255-265
Developer Environment Setup
For substantial changes, developers should work on a local clone to test builds.
Local Documentation Build
# Navigate to docusaurus directory
cd docusaurus
# Install dependencies
pnpm install
# Start development server
pnpm start
The development server typically runs at http://localhost:3005.
Sources: version-1.6/contributing-to-airbyte/writing-docs.md:85-95
Requirements
- Node.js & pnpm: Required for the Docusaurus frontend.
- Docker: Necessary for running and testing connectors locally.
- Git: Used for version control and PR submission.
Sources: version-2.0/contributing-to-airbyte/writing-docs.md:58-65
Summary
The Contribution and Developer Guidelines ensure that Airbyte remains a secure and reliable infrastructure component. By following the structured code workflow, adhering to documentation standards, and implementing connectors based on ELT principles, developers help maintain the project's high standards for data integrity. All contributions are subject to review by Airbyte maintainers and must pass automated CI checks including testing and linting.