path: root/openbb_platform/CONTRIBUTING.md

# Contributing to the OpenBB Platform

<!-- markdownlint-disable MD033 MD024 -->

- [Contributing to the OpenBB Platform](#contributing-to-the-openbb-platform)
  - [Introduction](#introduction)
    - [Quick look into the OpenBB Platform](#quick-look-into-the-openbb-platform)
      - [What is the Standardization Framework?](#what-is-the-standardization-framework)
        - [Standardization Caveats](#standardization-caveats)
        - [Standard QueryParams Example](#standard-queryparams-example)
        - [Standard Data Example](#standard-data-example)
      - [What is an extension?](#what-is-an-extension)
        - [Types of extensions](#types-of-extensions)
  - [Dependency Management](#dependency-management)
    - [High-Level Overview](#high-level-overview)
    - [Core Dependency Management](#core-dependency-management)
      - [Installation](#installation)
      - [Using Poetry](#using-poetry)
    - [Core and Extensions](#core-and-extensions)
      - [Installation](#installation-1)
      - [Dependency Management with Poetry](#dependency-management-with-poetry)
  - [Developer Guidelines](#developer-guidelines)
    - [Expectations for Developers](#expectations-for-developers)
    - [How to build OpenBB extensions?](#how-to-build-openbb-extensions)
    - [Building Extensions: Best Practices](#building-extensions-best-practices)
    - [How to add a new data point?](#how-to-add-a-new-data-point)
      - [Identify which type of data you want to add](#identify-which-type-of-data-you-want-to-add)
      - [Check if the standard model exists](#check-if-the-standard-model-exists)
        - [Create Query Parameters model](#create-query-parameters-model)
        - [Create Data Output model](#create-data-output-model)
        - [Build the Fetcher](#build-the-fetcher)
      - [Make the provider visible](#make-the-provider-visible)
    - [How to add custom data sources?](#how-to-add-custom-data-sources)
      - [OpenBB Platform commands](#openbb-platform-commands)
    - [Architectural considerations](#architectural-considerations)
      - [Important classes](#important-classes)
      - [Import statements](#import-statements)
      - [The TET pattern](#the-tet-pattern)
      - [Error](#errors)
      - [Data processing commands](#data-processing-commands)
        - [Python Interface](#python-interface)
        - [API Interface](#api-interface)
  - [Contributor Guidelines](#contributor-guidelines)
    - [Expectations for Contributors](#expectations-for-contributors)
    - [Quality Assurance](#quality-assurance)
      - [Unit tests](#unit-tests)
      - [Integration tests](#integration-tests)
      - [Import time](#import-time)
    - [Sharing your extension](#sharing-your-extension)
      - [Publish your extension to PyPI](#publish-your-extension-to-pypi)
        - [Setup](#setup)
        - [Release](#release)
        - [Publish](#publish)
    - [Manage extensions](#manage-extensions)
      - [Add an extension as a dependency](#add-an-extension-as-a-dependency)
    - [Write code and commit](#write-code-and-commit)
      - [How to create a PR?](#how-to-create-a-pr)
        - [Branch Naming Conventions](#branch-naming-conventions)

## Introduction

This document provides guidelines for contributing to the OpenBB Platform.
Throughout this document, we will be differentiating between two types of contributors: Developers and Contributors.

1. **Developers**: Those who are building new features or extensions for the OpenBB Platform or leveraging the OpenBB Platform.
2. **Contributors**: Those who contribute to the existing codebase, by opening a [Pull Request](#getting_started-create-a-pr) thus giving back to the community.

**Why is this distinction important?**

The OpenBB Platform is designed as a foundation for further development. We anticipate a wide range of creative use cases for it. Some use cases may be highly specific or detail-oriented, solving particular problems that may not necessarily fit within the OpenBB Platform Github repository. This is entirely acceptable and even encouraged. This document provides a comprehensive guide on how to build your own extensions, add new data points, and more.

The **Developer** role, as defined in this document, can be thought of as the foundational role. Developers are those who use the OpenBB Platform as is or build upon it.

Conversely, the **Contributor** role refers to those who enhance the OpenBB Platform codebase (either by directly adding to the OpenBB Platform or by extending the [extension repository](/openbb_platform/extensions/)). Contributors are willing to go the extra mile, spending additional time on quality assurance, testing, or collaborating with the OpenBB development team to ensure adherence to standards, thereby giving back to the community.

### Quick look into the OpenBB Platform

The OpenBB Platform is built by the Open-Source community and is characterized by its core and extensions. The core handles data integration and standardization, while the extensions enable customization and advanced functionalities. The OpenBB Platform is designed to be used both from a Python interface and a REST API.

The REST API is built on top of FastAPI and can be started by running the following command from the root:

```bash
uvicorn openbb_platform.core.openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload
```

The Python interfaces we provide to users is the `openbb` python package.

The code you will find in this package is generated from a script and it is just a wrapper around the `openbb-core` and any installed extensions.

When the user runs `import openbb`, `from openbb import obb` or other variants, the script that generates the packaged code is triggered. It detects if there are new extensions installed in the environment and rebuilds the packaged code accordingly. If new extensions are not found, it just uses the current packaged version.

When you are developing chances are you want to manually trigger the package rebuild.

You can do that with:

```python
python -c "import openbb; openbb.build()"
```

The Python interface can be imported with:

```python
from openbb import obb
```

This document will take you through two types of contributions:

1. Building a custom extension
2. Contributing directly to the OpenBB Platform

Before moving forward, please take a look at the high-level view of the OpenBB Platform architecture. We will go over each bit in this document.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/OpenBB-finance/OpenBBTerminal/assets/742661