Contributing¶
Thanks for your interest in contributing to Knowmarks. This guide covers development setup and submission guidelines.
Prerequisites¶
- Python 3.11+
- uv (recommended) or pip
Development Setup¶
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 commands
km save https://example.com
km find "search query"
km status
# Dashboard
km serve
# MCP server
km mcp
Testing¶
pytest # Run all tests
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
Submitting Changes¶
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes
- Run tests and linting:
pytest && ruff check src/ - Commit with a clear message
- 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. 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.