Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
94 lines (66 loc) · 2.07 KB

CONTRIBUTING.md

File metadata and controls

94 lines (66 loc) · 2.07 KB

Contributing to Knowmarks

Thanks for your interest in contributing! This guide covers how to set up a development environment and submit changes.

Development Setup

Prerequisites

  • Python 3.11+
  • uv (recommended) or pip

Install

git clone https://github.com/mcoliver/knowmarks.git
cd knowmarks
uv sync --all-extras

This installs all dependencies including dev tools (pytest, ruff).

Running

# CLI
km save https://example.com
km find "search query"

# Dashboard
km serve

# MCP server
km mcp

Testing

pytest
pytest tests/test_config.py -v     # specific test file
pytest -k "test_search"            # specific test name

Linting

ruff check src/
ruff format --check src/

Code Style

  • Follow existing patterns in the codebase
  • Use type hints for function signatures
  • Keep functions focused — one responsibility per function
  • No docstrings required for internal functions with clear names

Project Structure

src/knowmarks/
  cli.py          # Click CLI
  config.py       # Configuration and paths
  core/           # Business logic (db, search, embed, ingest, etc.)
  web/            # FastAPI dashboard + REST API
  mcp/            # MCP server

Submitting Changes

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Make your changes
  4. Run tests and linting (pytest && ruff check src/)
  5. Commit with a clear message
  6. Open a pull request

Pull Request Guidelines

  • Keep PRs focused on a single change
  • Include a clear description of what and why
  • Add tests for new functionality
  • Ensure all tests pass and linting is clean

Reporting Issues

Use GitHub Issues for bug reports and feature requests. Please include:

  • Bugs: Steps to reproduce, expected vs actual behavior, Python version, OS
  • Features: Description of the use case and proposed behavior

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.