Adds two test-discipline tools to the dev extras and closes a real contributor-onboarding gap in CONTRIBUTING.md that allowed PR #1579's 2026-05-22 4 AM ruff-version-mismatch lint failure. Adds to ``[project.optional-dependencies].dev`` (and matching ``[dependency-groups].dev`` for uv users): - **``hypothesis>=6.0``** — property-based testing framework. Generates hundreds of random inputs per test and shrinks failing cases to a minimal counterexample. Used opt-in (sprinkle ``@given(...)`` on a test); zero runtime cost on tests that don't use it. Would have caught the Tier 6a dateutil-fuzzy hallucination on PR #1584 with one property test. - **``pre-commit>=3.0``** — the pre-commit framework itself. ``.pre-commit-config.yaml`` already lives in the repo (committed by @igorls on 2026-05-18, pinned to ruff 0.15.9 in lockstep with CI). What was missing was making the framework a declared dev dependency so ``pip install -e .[dev]`` / ``uv sync --extra dev`` actually pulls it in. Adds a ``pre-commit install`` line to the Getting Started bash block plus a short paragraph explaining why this step is required (the hook file at ``.git/hooks/pre-commit`` is per-machine and NOT tracked by git, so the repo's ``.pre-commit-config.yaml`` only takes effect after each developer runs ``pre-commit install`` once locally). Adds an optional "Property-based tests" subsection under Running Tests showing the minimal ``@given(...)`` pattern, so contributors who want to reach for the new tool know it's available. On 2026-05-22 at 4:30 AM, PR #1579 (Tier 6a) hit a CI lint failure caused by a ruff version mismatch: my local machine had ruff 0.4.10, CI runs ruff 0.15.9 (pinned in pyproject.toml). The two versions produce different ``ruff format`` output for the same code. The repo HAD ``.pre-commit-config.yaml`` pinning ruff 0.15.9 — but the local git hook had never been wired on my machine because nothing in CONTRIBUTING.md said to run ``pre-commit install``. The protection existed at the project layer; the activation gap was at the contributor-onboarding layer. This commit closes that gap structurally. Anyone cloning the repo from now on sees ``pre-commit install`` as part of the Getting Started flow and is protected from the same failure. - **No ``mutmut`` in dev deps.** Mutation testing is heavier (runs the whole test suite per mutation) and useful periodically rather than every commit. Contributors who want to run it can install manually. Adding it to dev deps would bloat the install footprint for every contributor when most will never use it. - **No new property tests.** This PR ships the TOOL, not new test coverage. Property tests should land alongside the specific functions they cover, in their own PRs. - **No changes to ``.pre-commit-config.yaml``.** That file is correct as Igor wrote it. The fix here is purely making the framework installable + documenting the activation step. ruff check . → All checks passed. pre-commit run --all-files (locally) → ruff (legacy alias): Passed → ruff format: Passed OrbStack triple-Linux verify (Py 3.9 / 3.11 / 3.13) → ``pip install -e .[dev]`` resolves cleanly; hypothesis + pre_commit import successfully; existing test suite unaffected.
139 lines
5.2 KiB
Markdown
139 lines
5.2 KiB
Markdown
# Contributing to MemPalace
|
|
|
|
Thanks for wanting to help. MemPalace is open source and we welcome contributions of all sizes — from typo fixes to new features.
|
|
|
|
## Getting Started
|
|
|
|
```bash
|
|
# Fork the repo on GitHub first, then clone your fork
|
|
git clone https://github.com/<your-username>/mempalace.git
|
|
cd mempalace
|
|
git remote add upstream https://github.com/MemPalace/mempalace.git
|
|
|
|
# Recommended: uv (https://docs.astral.sh/uv/) handles the venv for you
|
|
uv sync --extra dev
|
|
|
|
# Or with pip in your own venv:
|
|
# pip install -e ".[dev]"
|
|
|
|
# Activate pre-commit hooks (one-time, per clone)
|
|
pre-commit install
|
|
```
|
|
|
|
The `pre-commit install` step is important: the repo has a
|
|
`.pre-commit-config.yaml` that pins ruff to the exact version CI uses,
|
|
but the actual git hook is per-machine and **must be installed
|
|
locally**. Without this step, you can commit code that passes your
|
|
local lint (using whatever ruff version you happen to have installed)
|
|
but fails CI on push.
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
uv run pytest tests/ -v
|
|
```
|
|
|
|
All tests must pass before submitting a PR. Tests should run without API keys or network access.
|
|
|
|
### Property-based tests (optional)
|
|
|
|
`hypothesis` is available in the dev extras for property-based tests:
|
|
|
|
```python
|
|
from hypothesis import given, strategies as st
|
|
|
|
@given(st.text(min_size=1, max_size=40))
|
|
def test_function_never_fabricates_output_on_random_input(s):
|
|
# ... property that must hold for ANY string in the strategy
|
|
```
|
|
|
|
Hypothesis generates hundreds of inputs per test and shrinks failing
|
|
cases to a minimal counterexample. Useful any time a function returns
|
|
`Optional[X]` or has a wide input domain — it catches the failure-space
|
|
gaps that hand-written positive tests miss.
|
|
|
|
## Running Benchmarks
|
|
|
|
```bash
|
|
# Quick test (20 questions, ~30 seconds)
|
|
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json --limit 20
|
|
|
|
# Full benchmark (500 questions, ~5 minutes)
|
|
uv run python benchmarks/longmemeval_bench.py /path/to/longmemeval_s_cleaned.json
|
|
```
|
|
|
|
See [benchmarks/README.md](benchmarks/README.md) for data download instructions and reproduction guide.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
mempalace/ ← core package (see mempalace/README.md for module guide)
|
|
benchmarks/ ← reproducible benchmark runners
|
|
hooks/ ← Claude Code auto-save hooks
|
|
examples/ ← usage examples
|
|
tests/ ← test suite
|
|
assets/ ← logo + brand
|
|
```
|
|
|
|
## PR Guidelines
|
|
|
|
1. Fork the repo and create a feature branch: `git checkout -b feat/my-thing`
|
|
2. Write your code
|
|
3. Add or update tests if applicable
|
|
4. Run `uv run pytest tests/ -v` — everything must pass
|
|
5. Commit with a clear message following [conventional commits](https://www.conventionalcommits.org/):
|
|
- `feat: add Notion export format`
|
|
- `fix: handle empty transcript files`
|
|
- `docs: update MCP tool descriptions`
|
|
- `bench: add LoCoMo turn-level metrics`
|
|
6. Push to your fork and open a PR against `develop`
|
|
|
|
## Code Style
|
|
|
|
- **Formatting**: [Ruff](https://docs.astral.sh/ruff/) with 100-char line limit (configured in `pyproject.toml`)
|
|
- **Naming**: `snake_case` for functions/variables, `PascalCase` for classes
|
|
- **Docstrings**: on all modules and public functions
|
|
- **Type hints**: where they improve readability
|
|
- **Dependencies**: minimize. ChromaDB + PyYAML only. Don't add new deps without discussion.
|
|
|
|
## Good First Issues
|
|
|
|
Check the [Issues](https://github.com/MemPalace/mempalace/issues) tab. Great starting points:
|
|
|
|
- **New chat formats**: Add import support for Cursor, Copilot, or other AI tool exports
|
|
- **Room detection**: Improve pattern matching in `room_detector_local.py`
|
|
- **Tests**: Increase coverage — especially for `knowledge_graph.py` and `palace_graph.py`
|
|
- **Entity detection**: Better name disambiguation in `entity_detector.py`
|
|
- **Docs**: Improve examples, add tutorials
|
|
|
|
## Architecture Decisions
|
|
|
|
If you're planning a significant change, open an issue first to discuss the approach. Key principles:
|
|
|
|
- **Verbatim first**: Never summarize user content. Store exact words.
|
|
- **Local first**: Everything runs on the user's machine. No cloud dependencies.
|
|
- **Zero API by default**: Core features must work without any API key.
|
|
- **Palace structure is scoping, not magic**: Wings, halls, and rooms act as metadata filters in the underlying vector store. They keep retrieval predictable when a palace holds many unrelated projects or people. Respect the hierarchy — but don't present it as a novel retrieval mechanism.
|
|
|
|
## Community
|
|
|
|
- **Discord**: [Join us](https://discord.com/invite/ycTQQCu6kn)
|
|
- **Issues**: Bug reports and feature requests welcome
|
|
- **Discussions**: For questions and ideas
|
|
|
|
## License
|
|
|
|
MIT — your contributions will be released under the same license.
|
|
|
|
## Git identity for contributions
|
|
|
|
Before pushing commits, verify that Git is configured with an email address that GitHub can associate with your account:
|
|
|
|
```bash
|
|
git config user.name
|
|
git config user.email
|
|
```
|
|
|
|
This is especially important when commits are created through agentic coding tools or automation, because those tools may not inherit your normal shell Git configuration. Avoid placeholder values such as `your@email.com` or localized template text; unresolved author emails can create avoidable provenance and SBOM review friction for downstream users.
|
|
|