Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (106 loc) · 2.97 KB

CONTRIBUTING.md

File metadata and controls

134 lines (106 loc) · 2.97 KB
Raw

Contributing

Thank you for contributing! This document explains how to get a local development environment running, run tests, and submit a PR.

Prerequisites

  • Git
  • Python 3.10+ (recommended)
  • Poetry (or pip + virtualenv)
  • Docker & Docker Compose
  • (Optional) OpenAI API key if you plan to run examples that generate embeddings or use an LLM

Development Setup

  1. Clone the repo:
git clone https://github.com/oceanbase/langchain-oceanbase.git
cd langchain-oceanbase
  1. Create a virtual environment and install dependencies:
  • With Poetry:
poetry install
poetry shell
  • With pip:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
  1. Bring up the local database for development (OceanBase):
make docker-up
# or for SeekDB lightweight alternative:
make docker-up-seek
  1. Environment variables (examples) Create a .env file or export environment variables:
OB_HOST=127.0.0.1
OB_PORT=3306
OB_USER=root
OB_PASSWORD=yourpassword
OB_DB=langchain_ob_demo
OPENAI_API_KEY=sk-xxxx

Running tests

  • Unit tests:
pytest tests/unit
  • Integration tests (requires docker-compose services up):
make docker-up
pytest tests/integration
  • Linting / type checks:
ruff check .
mypy .

Code style

  • Formatting: black
  • Linting: ruff
  • Type checks: mypy
  • Commit messages: follow Conventional Commits or keep concise, descriptive messages.

Submitting PRs

  1. Start from the correct base branch:

    • Regular work starts from develop
    • Releases start from develop
    • Hotfixes start from main

  2. Create a branch with a git-flow style name:

git checkout -b feature/onboard-docker-compose origin/develop

Examples:

git checkout -b bugfix/fix-seekdb-timeout origin/develop
git checkout -b release/0.3.4 origin/develop
git checkout -b hotfix/restore-ci origin/main

  1. Make edits and add tests where applicable.

  2. Run tests and linters locally.

  3. Commit changes:

git add .
git commit -m "feat: add docker-compose and onboarding docs"
git push origin feature/onboard-docker-compose
  1. Open a PR describing the change. Use these git-flow targets:
  • feature/*, bugfix/*, chore/*, docs/*, refactor/*, test/* -> develop
  • release/* -> main
  • hotfix/* -> main, then back-merge to develop
  • Dependabot version updates target develop
  • Dependabot security updates still follow the GitHub default branch until a repo admin switches the default branch from main to develop

Include:

  • Problem you're solving
  • Any migration or manual steps
  • Testing steps

PR review checklist

  • Tests added/updated
  • Linting passes
  • Clear description & motivation
  • Updated docs if needed

Makefile targets

  • make docker-up — start OceanBase
  • make docker-up-seek — start SeekDB (alternative)
  • make docker-down — stop OceanBase and remove volumes
  • make docker-logs — follow OceanBase logs

Thank you for contributing!