Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (96 loc) · 4.64 KB

CONTRIBUTING.md

File metadata and controls

135 lines (96 loc) · 4.64 KB

Contributing to SocratiCode

Thank you for your interest in contributing to SocratiCode! This document explains the process for contributing and what to expect.

Contributor License Agreement

By submitting a pull request, you agree to the Contributor License Agreement (CLA). This is necessary because SocratiCode is dual-licensed (AGPL-3.0 + commercial). The CLA allows us to offer commercial licenses that include community contributions.

Getting Started

Prerequisites

  • Node.js 18+
  • Docker (for integration and E2E tests)
  • Git

Setup

git clone https://github.com/giancarloerra/socraticode.git
cd socraticode
npm install
npm run build

Running Tests

# Unit tests (no Docker needed)
npm run test:unit

# Integration tests (requires Docker)
npm run test:integration

# End-to-end tests (requires Docker)
npm run test:e2e

# All tests
npm test

# Type checking
npx tsc --noEmit

See the Developer Guide for architecture details, data flows, and how the test infrastructure works.

How to Contribute

Reporting Bugs

Use the Bug Report issue template. Include:

  • Steps to reproduce
  • Expected vs actual behaviour
  • Your environment (OS, Node.js version, embedding provider, MCP host)
  • Log output if available (set SOCRATICODE_LOG_LEVEL=debug)

Suggesting Features

Use the Feature Request issue template. Explain the problem you're trying to solve and your proposed approach.

Submitting Pull Requests

  1. Fork the repository and create a branch from main
  2. Make your changes — follow the existing code style and conventions
  3. Add tests — new functionality needs test coverage; bug fixes should include a regression test
  4. Update documentation — if your changes affect the public API, update README.md and/or DEVELOPER.md
  5. Verify — run npm run lint && npx tsc --noEmit && npm run test:unit
  6. Open a PR — fill out the pull request template

Commit Message Convention

We use Conventional Commits to auto-generate the changelog:

feat: add fuzzy search support
fix: resolve race condition in watcher
docs: update quickstart guide
refactor: simplify provider factory
test: add watcher edge-case tests
chore: update dependencies

Prefix with the type, then a short imperative description. Use feat: for new features, fix: for bug fixes, and chore: for maintenance that doesn't need a changelog entry.

What Makes a Good PR

  • Focused — one logical change per PR
  • Tested — unit tests at minimum; integration tests for infrastructure changes
  • Documented — JSDoc comments on public functions, README/DEVELOPER.md updates where needed
  • Clean history — squash fixup commits before requesting review
  • Conventional commits — use the format above so the changelog generates correctly

Code Style

  • TypeScript with strict mode enabled
  • ESM (ES modules) — use .js extensions in imports
  • Functional style — prefer pure functions, avoid classes where unnecessary
  • Structured logging — use logger.info/warn/error/debug with context objects, not console.log
  • Error messages — user-friendly, actionable, include troubleshooting hints
  • JSDoc on all exported functions
  • SPDX license header on all source files: 
    // SPDX-License-Identifier: AGPL-3.0-only
// Copyright (C) 2026 Giancarlo Erra - Altaire Limited

Project Structure

src/services/   — Core business logic (docker, indexer, embeddings, etc.)
src/tools/      — MCP tool handlers (one file per tool group)
src/config.ts   — Project ID and collection naming
src/constants.ts — All configurable constants
tests/unit/     — Unit tests (no Docker)
tests/integration/ — Integration tests (Docker required)
tests/e2e/      — End-to-end tests (Docker required)

See DEVELOPER.md for the full architecture overview.

Review Process

  • All PRs are reviewed by a maintainer
  • CodeRabbit automatically reviews every PR — address or resolve all comments before requesting human review
  • CI must pass (tests + type checking)
  • One approval required to merge
  • Maintainers may request changes or suggest alternatives

Questions?

Thank you for helping make SocratiCode better!