Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
182 lines (137 loc) · 4.97 KB

CONTRIBUTING.md

File metadata and controls

182 lines (137 loc) · 4.97 KB

Contributing to SeeQL

Thank you for your interest in contributing to SeeQL! This document outlines the contribution process and guidelines.

Understanding the Project Intent

Before contributing, please take time to understand the core purpose of seeQL:

SeeQL is an AI-powered conversational interface for querying databases using natural language. Built with Next.js and the Model Context Protocol (MCP), it enables users to ask questions in plain English and receive rich, visual dashboards (Charts, Graphs, Tables) instead of raw SQL results.

The project emphasizes:

  • Natural Language to SQL: Accurate translation from conversation to structured data queries
  • Dynamic Visualizations: Automatic rendering of appropriate dashboards based on result sets
  • MCP Integration: Transparent database schemas and secure tool endpoints
  • Developer Experience: Fast iteration using Next.js and TypeScript

Contribution Process

1. Create an Issue First

Always create an issue before starting work. This ensures:

  • Your contribution aligns with project goals
  • No duplicate work
  • Proper discussion and planning
  • Clear acceptance criteria

Issue Types:

  • 🐛 Bug Report: Something isn't working
  • ✨ Feature Request: New functionality
  • 📚 Documentation: Improvements or additions
  • 🔧 Enhancement: Improvements to existing features
  • ❓ Question: General inquiries

2. Development Workflow

Once your issue is approved:

  1. Fork the repository
  2. Create a feature branch from main: 
    git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-description
# or
git checkout -b docs/add-hooks-documentation
  3. Make your changes following our coding standards
  4. Update documentation if needed
  5. Verify locally by testing the app in your browser
  6. Commit with clear messages: 
    git commit -m "feat: add new hook for component state management

- Implements useComponentState hook
- Adds TypeScript types
- Includes comprehensive tests
- Updates documentation

Closes #123"

3. Pull Request Process

  1. Push your branch to your fork
  2. Create a Pull Request targeting the main branch
  3. Fill out the PR template completely
  4. Request review from maintainers
  5. Address feedback and make requested changes
  6. Wait for approval and merge

Branch Naming Convention

  • feature/description-of-feature
  • fix/issue-number-description
  • docs/add-documentation
  • refactor/component-improvements
  • test/add-unit-tests

Commit Message Format

We follow conventional commits:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation
  • style: Code style changes
  • refactor: Code refactoring
  • test: Adding tests
  • chore: Maintenance

Examples:

feat: add bar chart visualizer for query data
fix: resolve database connection timeout
docs: update setup and config details in README
style: fix layout spacing overflow on dashboard components

Code Guidelines

TypeScript

  • Strict TypeScript usage
  • Proper type definitions for all exports
  • Use interfaces over types for public APIs

React Components

  • Functional components with hooks
  • Proper TypeScript typing
  • Consistent naming conventions
  • Accessibility considerations

MCP Servers

  • Follow MCP protocol standards
  • Proper error handling
  • Structured content for component integration
  • Clear tool descriptions

Verification & Validation

  • Required: Manually verify your features or fixes work correctly inside the conversation interface
  • Ensure accurate SQL mapping for generic or loaded queries where applicable
  • Verify dashboard layouts with large dataset visualizers if making changes to responses
  • Feel free to help us introduce standard testing frameworks if you're interested!

Documentation

  • JSDoc comments for public APIs
  • README updates for new features
  • Example code in documentation
  • Clear installation and usage instructions

Development Setup

# Clone the repository
git clone https://github.com/maneeshsandra/seeQL.git
cd seeQL

# Install dependencies
npm install

# Setup environment variables 
# (See README.md for creating an .env file)

# Development
npm run dev          # Start dev server
npm run build        # Build for production

Code Review Process

All PRs require review. Reviewers will check for:

  • ✅ Code quality and style
  • ✅ Manual verification results or test coverage (if added)
  • ✅ Documentation updates
  • ✅ Breaking changes clearly marked
  • ✅ Performance implications
  • ✅ Security considerations

Recognition

Contributors are recognized through:

  • GitHub contributor statistics
  • Mention in release notes
  • Attribution in documentation

Questions?

  • Check existing issues and documentation first
  • Create a discussion for questions
  • Join our community chats

Thank you for contributing to SeeQL! 🚀