Contribution Guidelines¶
Thanks for considering contributing to OPEA project. The contribution process is similar with other open source projects on Github, involving an amount of open discussion in issues and feature requests between the maintainers, contributors and users.
All The Ways To Contribute¶
Contribute a GenAI Component¶
Navigate to OPEA GenAIComps and locate the component folder your integration belongs to. If the microservice type already exists, review the OPEA microservice API and follow it in your implementation. Otherwise, if you are contributing a brand new microservice type, you need to define and contribute first its API specification. Please start by submitting an RFC to get community feedback.
GenAIComps ├── comps │ ├── agent │ ├── asr │ ├── chathistory │ ├── cores │ │ ├── mega #orchestrator, gateway, micro_service class code │ │ ├── proto #api protocol │ │ └── telemetry │ ├── dataprep │ ├── embeddings │ ├── feedback_management │ ├── finetuning │ ├── guardrails │ ├── intent_detection │ ├── knowledgegraphs │ ├── llms │ ├── lvms │ ├── nginx │ ├── prompt_registry │ ├── ragas │ ├── reranks │ ├── retrievers │ ├── tts │ ├── vectorstores │ └── web_retrievers └── tests ├── agent ├── asr ├── chathistory ├── cores ├── dataprep ├── embeddings ├── feedback_management ├── finetuning ├── guardrails ├── intent_detection ├── llms ├── lvms ├── nginx ├── prompt_registry ├── reranks ├── retrievers ├── tts ├── vectorstores └── web_retrievers
Follow the folder structure in the TEI embedding component below:
GenAIComps ├── comps │ └── embeddings │ ├── __init__.py │ └── tei #vendor name or serving framework name │ ├── langchain │ │ ├── Dockerfile │ │ ├── Dockerfile.amd_gpu │ │ ├── Dockerfile.nvidia_gpu │ │ ├── embedding_tei.py # definition and registration of microservice │ │ ├── README.md │ │ └── requirements.txt │ └── llama_index │ └── . . . ├── tests │ └── embeddings │ ├── test_embeddings_tei_langchain.sh │ ├── test_embeddings_tei_langchain_on_amd_gpu.sh │ └── test_embeddings_tei_llama_index.sh └── README.md
File Descriptions:
embedding_tei.py: This file defines and registers the microservice. It serves as the entrypoint of the Docker container. Refer to whisper ASR for a simple example or TGI for a more complex example that required adapting to the OpenAI API.requirements.txt: This file is used by Docker to install the necessary dependencies.Dockerfile: Used to generate the service container image. Please follow naming conventions:Dockerfile:
Dockerfile.[vendor]_[hardware], vendor and hardware in lower case (i,e Dockerfile.amd_gpu)Docker Image:
opea/[microservice type]-[microservice sub type]-[library name]-[vendor]-[hardware]:latestall lower case (i,e opea/llm-vllm-intel-hpu, opea/llm-faqgen-tgi-intel-hpu-svc)
tests/[microservices type]/: contains end-to-end test for microservices Please refer to an example test_asr_whisper.sh. Please follow naming convention:test_[microservice type]_[microservice sub type]_[library name]_on_[vendor]_[hardware].shtests/cores/: contains Unit Tests (UT) for the core python components (orchestrator, gateway…). Please follow the naming convention:test_[core component].shREADME.md: at minimum it should include: microservice description, build, and start commands and a curl command with expected output.
Now you have created all the required files, and validated your service. Last step is to modify the
README.mdat the component levelGenAIComps/comps/[microservice type]to list your new component. Now you are ready to file your PR! Once your PR is merged, in the next release the project release maintainers will publish the Docker Image for the same to the Docker Hub.After your component has been merged, you are likely interested in building an application with it, and perhaps contributing it also to OPEA! Please continue on to the Contribute a GenAI Example guide.
Contribute a GenAI Example¶
Each of the samples in OPEA GenAIExamples are a common oft used solution. They each have scripts to ease deployment, and have been tested for performance and scalability with Docker compose and Kubernetes. When contributing an example, a Docker Compose deployment is the minimum requirement. However, since OPEA is intended for enterprise applications, supporting Kubernetes deployment is highly encouraged. You can find examples for Kubernetes deployment using manifests, Helms Charts, and the GenAI Microservices Connector (GMC). GMC offers additional enterprise features, such as the ability to dynamically adjust pipelines on Kubernetes (e.g., switching to a different LLM on the fly, adding guardrails), composing pipeleines that include external services hosted in public cloud or on-premisees via URL, and supporting sequential, parallel and conditional flows in the pipelines.
Navigate to OPEA GenAIExamples and check the catalog of examples. If you find one that is very similar to what you are looking for, you can contribute your variation of it to that particular example folder. If you are bringing a completly new application you will need to create a separate example folder.
Before stitching together all the microservices to build your application, let’s make sure all the required building blocks are available!. Take a look at this ChatQnA Flow Chart:
OPEA uses gateways to handle requests and route them to the corresponding megaservices (unless you have an agent that will otherwise handle the gateway function). If you are just making small changes to the application, like swaping one DB for another, you can reuse the existing Gateway but if you are contributing a completely new application, you will need to add a Gateway class. Navigate to OPEA GenAIComps Gateway and implement how Gateway should handle requests for your application. Note that Gateway implementation is moving to GenAIExamples in future release.
Follow the folder structure in the ChatQA example below:
├── assets ├── benchmark # optional ├── chatqna.py # Main application definition (microservices, megaservice, gateway). ├── chatqna.yaml # starting v1.0 used to generate manifests for k8s w orchestrator_with_yaml ├── docker_compose │ ├── intel │ │ ├── cpu │ │ │ └── xeon │ │ │ ├── compose.yaml │ │ │ ├── README.md │ │ │ └── set_env.sh #export env variables │ │ └── hpu │ │ └── gaudi │ │ ├── compose.yaml │ │ ├── how_to_validate_service.md #optional │ │ ├── README.md │ │ └── set_env.sh │ └── nvidia │ └── gpu │ ├── compose.yaml │ ├── README.md │ └── set_env.sh ├── Dockerfile ├── docker_image_build │ └── build.yaml ├── kubernetes │ ├── intel │ │ ├── cpu │ │ │ └── xeon │ │ │ ├── gmc │ │ │ │ └── chatQnA_xeon.yaml │ │ │ └── manifest │ │ │ └── chatqna.yaml │ │ └── hpu │ │ └── gaudi │ │ ├── gmc │ │ │ └── chatQnA_gaudi.yaml │ │ └── manifest │ │ └── chatqna.yaml │ ├── amd │ │ ├── cpu │ │ │ ├── gmc │ │ │ └── manifest │ │ └── gpu │ │ ├── gmc │ │ └── manifest │ ├── README_gmc.md # K8s quickstar │ └── README.md # quickstart ├── README.md ├── tests │ ├── test_compose_on_gaudi.sh #could be more tests for different flavors of the app │ ├── test_gmc_on_gaudi.sh │ ├── test_manifest_on_gaudi.sh └── ui
File Descriptions:
chatqna.py: application definition using microservice, megaservice and gateway. There could be multiple .py in the folder based on slight modification of the example application.docker_build_image/build.yaml: builds necessary images pointing to the Dockerfiles in the GenAIComp repository.docker_compose/vendor/device/compose.yaml: defines pipeline for Docker compose deployment. For selectng docker image name please follow the naming convention:Docker Image:
opea/[example name]-[feature name]:latestall lower case (i,e: opea/chatqna, opea/codegen-react-ui)
kubernetes/vendor/device/manifests/chatqna.yaml: used for K8s deployemntkubernetes/vendor/device/gmc/chatqna.yaml: (optional) used for deployment with GMCtests/: at minimum you need to provide an E2E test with Docker compose. If you are contritbutng K8s manifests and GMC yaml, you should also provide test for those. Please follow naming convention:Docker compose test:
tests/test_compose_on_[hardware].shK8s test:
tests/test_manifest_on_[hardware].shK8s with GMC test:
tests/test_gmc_on_[hardware].sh
ui: (optional)assets: nice to have an application flow diagram
Additional steps if your contribution is Hardware Specific¶
You will need additional steps to configure the CI/CD for first testing and then deploying your merged GenAIComp or GenAIExample.
Connect hardware into OPEA GitHub Actions (GHA) as a self-hosted runner
Contribute test scripts for the new hardware
Dockerfile for the Component (i,e
GenAIComp/comps/llm/text-generation/tgi/Dockerfile.[vendor]_[hardware])Update the image build yaml for new images
Update the CI/CD workflow to identify and deploy new test
OPEA maintainer @chensuyue can assist in this process.
Community Discussions¶
Developers are encouraged to participate in discussions by opening an issue in one of the GitHub repos at https://github.com/opea-project. Alternatively, they can send an email to info@opea.dev or subscribe to X/Twitter and LinkedIn Page to get latest updates about the OPEA project.
Documentation¶
The quality of OPEA project’s documentation can have a huge impact on its success. We reply on OPEA maintainers and contributors to build clear, detailed and update-to-date documentation for user.
Reporting Issues¶
If OPEA user runs into some unexpected behavior, reporting the issue to the Issues page under the corresponding github project is the proper way to do. Please ensure there is no similar one already existing on the issue list). Please follow the Bug Report template and supply as much information as you can, and any additional insights you might have. It’s helpful if the issue submitter can narrow down the problematic behavior to a minimal reproducible test case.
Proposing New Features¶
OPEA communities use the RFC (request for comments) process for collaborating on substantial changes to OPEA projects. The RFC process allows the contributors to collaborate during the design process, providing clarity and validation before jumping to implementation.
When the RFC process is needed?
The RFC process is necessary for changes which have a substantial impact on end users, workflow, or user facing API. It generally includes:
Changes to core workflow.
Changes with significant architectural implications.
changes which modify or introduce user facing interfaces.
It is not necessary for changes like:
Bug fixes and optimizations with no semantic change.
Small features which doesn’t involve workflow or interface change, and only impact a narrow use case.
Step-by-Step guidelines¶
Follow this RFC Template to propose your idea (found in the docs repo community/rfcs/rfc_template.txt):
# RFC Template Replace the "RFC Template" heading with your RFC Title, followed by the short description of the feature you want to contribute ## Author(s) List all contributors of this RFC. ## Status Change the PR status to `Under Review` | `Rejected` | `Accepted`. ## Objective List what problem will this solve? What are the goals and non-goals of this RFC? ## Motivation List why this problem is valuable to solve? Whether some related work exists? ## Design Proposal This is the heart of the document, used to elaborate the design philosophy and detail proposal. ## Alternatives Considered List other alternatives if have, and corresponding pros/cons to each proposal. ## Compatibility list possible incompatible interface or workflow changes if exists. ## Miscellaneous List other information user and developer may care about, such as: - Performance Impact, such as speed, memory, accuracy. - Engineering Impact, such as binary size, startup time, build time, test times. - Security Impact, such as code vulnerability. - TODO List or staging plan.
Submit the proposal to the
Issuespage of the corresponding OPEA github repository.Reach out to your RFC’s assignee if you need any help with the RFC process.
Amend your proposal in response to reviewer’s feedback.
Submitting Pull Requests¶
Create Pull Request¶
If you have improvements to OPEA projects, send your pull requests to each project for review. If you are new to GitHub, view the pull request How To.
Step-by-Step guidelines¶
Star this repository using the button
Starin the top right corner.Fork the corresponding OPEA repository using the button
Forkin the top right corner.Clone your forked repository to your pc by running
git clone "url to your repo"Create a new branch for your modifications by running
git checkout -b new-branchAdd your files with
git add -A, commitgit commit -s -m "This is my commit message"and pushgit push origin new-branch.Create a
pull requestfor the project you want to contribute.
Pull Request Template¶
When you submit a PR, you’ll be presented with a PR template that looks something like this:
## Description
The summary of the proposed changes as long as the relevant motivation and context.
## Issues
List the issue or RFC link this PR is working on. If there is no such link, please mark it as `n/a`.
## Type of change
List the type of change like below. Please delete options that are not relevant.
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds new functionality)
- [ ] Breaking change (fix or feature that would break existing design and interface)
- [ ] Others (enhancement, documentation, validation, etc.)
## Dependencies
List the newly introduced 3rd party dependency if exists.
## Tests
Describe the tests that you ran to verify your changes.
Pull Request Acceptance Criteria¶
At least two approvals from reviewers
All detected status checks pass
All conversations solved
Third-party dependency license compatible
Pull Request Status Checks Overview¶
The OPEA projects use GitHub Action for CI test.
Test Name |
Test Scope |
Test Pass Criteria |
|---|---|---|
DCO |
Use |
PASS |
Code Format Scan |
pre-commit.ci [Bot] |
PASS |
Code Security Scan |
Bandit/Hadolint/Dependabot/CodeQL/Trellix |
PASS |
Unit Test |
Unit test under test folder |
PASS |
End to End Test |
End to end test workflow |
PASS |
Developer Certificate of Origin (DCO), the PR must agree to the terms of Developer Certificate of Origin by signing off each of commits with
-s, e.g.git commit -s -m 'This is my commit message'.Unit Test, the PR must pass all unit tests and without coverage regression.
End to End Test, the PR must pass all end to end tests.
Pull Request Review¶
You can add reviewers from the code owners list to your PR.
Support¶
Feel free to reach out to OPEA maintainers for support.
Submit your questions, feature requests, and bug reports to the GitHub issues page.
Contributor Covenant Code of Conduct¶
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant Code of Conduct.