CONTRIBUTING.md

Contributing to Schema Descriptor

Thank you for your interest in contributing to Schema Descriptor! This document provides guidelines and instructions for contributing to this project.

Table of Contents

• Code of Conduct
• Getting Started
• Development Environment
• Making Changes
• Testing
• Pull Request Process
• Known Issues

Code of Conduct

Please be respectful and considerate when contributing to this project. Treat others as you would like to be treated.

Getting Started

1. Fork the repository on GitHub
2. Clone your fork locally
3. Add the original repository as a remote named "upstream"

   git remote add upstream https://github.com/original/schema_descriptor.git
   

4. Create a new branch for your changes

   git checkout -b feature/your-feature-name
   

Development Environment

Setting Up

1. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install dependencies in the correct order:

   # Install key dependencies with specific versions first
   pip install protobuf==3.20.3
   pip install altair==4.2.2
   pip install streamlit==1.12.0
   pip install openai==0.28.0
   
   # Install remaining packages
   pip install -r requirements.txt --no-deps
   
   # Install test dependencies
   pip install -r requirements-test.txt
   

Dependency Management

This project has strict dependency constraints:

• protobuf: Must be exactly 3.20.3 for compatibility with both Streamlit and Google libraries
• altair: Must be 4.2.2 for compatibility with Streamlit 1.12.0
• streamlit: Version 1.12.0 is used in this project
• openai: Version 0.28.0 is compatible with our API integration

If you need to add a new dependency, please verify it doesn't conflict with these constraints before submitting a PR.

Making Changes

1. Make your changes in your feature branch
2. Follow the existing code style:
   • Use meaningful variable and function names
   • Add docstrings to functions
   • Follow PEP 8 guidelines
3. Keep changes focused on a single issue or feature

Testing

Run the test suite before submitting changes:

python tests/run_tests.py

Note: Some tests may currently fail due to ongoing development. See the Known Issues section.

If you add new functionality, please also add appropriate tests.

Pull Request Process

1. Update your fork to include the latest changes from upstream:

   git fetch upstream
   git merge upstream/main
   

2. Ensure your code passes the tests and linting

3. Create a pull request with:

   • A clear title
   • A description of the changes
   • Reference to any issues it addresses

4. Wait for review and be prepared to address feedback

Known Issues

The following issues are currently known and being worked on:

1. Test failures: Several tests in the test suite are currently failing due to:

   • Mocking issues with BigQuery Service
   • LLM Service test inconsistencies

2. Dependency conflicts: The project has strict dependency requirements to maintain compatibility between Streamlit, BigQuery, and OpenAI libraries.

If you encounter these issues, please refer to this section before submitting a bug report.

Thank you for contributing!