pyr0ball
8cb636dabe
Adds a full MkDocs documentation site under docs/ with Material theme. Getting Started: installation walkthrough, 7-step first-run wizard guide, Docker Compose profile reference with GPU memory guidance and preflight.py description. User Guide: job discovery (search profiles, custom boards, enrichment), job review (sorting, match scores, batch actions), apply workspace (cover letter gen, PDF export, mark applied), interviews (kanban stages, company research auto-trigger, survey assistant), email sync (IMAP, Gmail App Password, classification labels, stage auto-updates), integrations (all 13 drivers with tier requirements), settings (every tab documented). Developer Guide: contributing (dev env setup, code style, branch naming, PR checklist), architecture (ASCII layer diagram, design decisions), adding scrapers (full scrape() interface, registration, search profile config, test patterns), adding integrations (IntegrationBase full interface, auto- discovery, tier gating, test patterns), testing (patterns, fixtures, what not to test). Reference: tier system (full FEATURES table, can_use/tier_label API, dev override, adding gates), LLM router (backend types, complete() signature, fallback chains, vision routing, __auto__ resolution, adding backends), config files (every file with field-level docs and gitignore status). Also adds CONTRIBUTING.md at repo root pointing to the docs site.
120 lines
4 KiB
Markdown
120 lines
4 KiB
Markdown
# Contributing
|
|
|
|
Thank you for your interest in contributing to Peregrine. This guide covers the development environment, code standards, test requirements, and pull request process.
|
|
|
|
!!! note "License"
|
|
Peregrine uses a dual licence. The discovery pipeline (`scripts/discover.py`, `scripts/match.py`, `scripts/db.py`, `scripts/custom_boards/`) is MIT. All AI features, the UI, and everything else is BSL 1.1.
|
|
Do not add `Co-Authored-By:` trailers or AI-attribution notices to commits — this is a commercial repository.
|
|
|
|
---
|
|
|
|
## Fork and Clone
|
|
|
|
```bash
|
|
git clone https://git.circuitforge.io/circuitforge/peregrine
|
|
cd peregrine
|
|
```
|
|
|
|
Create a feature branch from `main`:
|
|
|
|
```bash
|
|
git checkout -b feat/my-feature
|
|
```
|
|
|
|
---
|
|
|
|
## Dev Environment Setup
|
|
|
|
Peregrine's Python dependencies are managed with conda. The same `job-seeker` environment is used for both the legacy personal app and Peregrine.
|
|
|
|
```bash
|
|
# Create the environment from the lockfile
|
|
conda env create -f environment.yml
|
|
|
|
# Activate
|
|
conda activate job-seeker
|
|
```
|
|
|
|
Alternatively, install from `requirements.txt` into an existing Python 3.12 environment:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
!!! warning "Keep the env lightweight"
|
|
Do not add `torch`, `sentence-transformers`, `bitsandbytes`, `transformers`, or any other CUDA/GPU package to the main environment. These live in separate conda environments (`job-seeker-vision` for the vision service, `ogma` for fine-tuning). Adding them to the main env causes out-of-memory failures during test runs.
|
|
|
|
---
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
conda run -n job-seeker python -m pytest tests/ -v
|
|
```
|
|
|
|
Or with the direct binary (avoids runaway process spawning):
|
|
|
|
```bash
|
|
/path/to/miniconda3/envs/job-seeker/bin/pytest tests/ -v
|
|
```
|
|
|
|
The `pytest.ini` file scopes collection to the `tests/` directory only — do not widen this.
|
|
|
|
All tests must pass before submitting a PR. See [Testing](testing.md) for patterns and conventions.
|
|
|
|
---
|
|
|
|
## Code Style
|
|
|
|
- **PEP 8** for all Python code — use `flake8` or `ruff` to check
|
|
- **Type hints preferred** on function signatures — not required but strongly encouraged
|
|
- **Docstrings** on all public functions and classes
|
|
- **No print statements** in library code (`scripts/`); use Python's `logging` module or return status in the return value. `print` is acceptable in one-off scripts and `discover.py`-style entry points.
|
|
|
|
---
|
|
|
|
## Branch Naming
|
|
|
|
| Prefix | Use for |
|
|
|--------|---------|
|
|
| `feat/` | New features |
|
|
| `fix/` | Bug fixes |
|
|
| `docs/` | Documentation only |
|
|
| `refactor/` | Code reorganisation without behaviour change |
|
|
| `test/` | Test additions or corrections |
|
|
| `chore/` | Dependency updates, CI, tooling |
|
|
|
|
Example: `feat/add-greenhouse-scraper`, `fix/email-imap-timeout`, `docs/add-integration-guide`
|
|
|
|
---
|
|
|
|
## PR Checklist
|
|
|
|
Before opening a pull request:
|
|
|
|
- [ ] All tests pass: `conda run -n job-seeker python -m pytest tests/ -v`
|
|
- [ ] New behaviour is covered by at least one test
|
|
- [ ] No new dependencies added to `environment.yml` or `requirements.txt` without a clear justification in the PR description
|
|
- [ ] Documentation updated if the PR changes user-visible behaviour (update the relevant page in `docs/`)
|
|
- [ ] Config file changes are reflected in the `.example` file
|
|
- [ ] No secrets, tokens, or personal data in any committed file
|
|
- [ ] Gitignored files (`config/*.yaml`, `staging.db`, `aihawk/`, `.env`) are not committed
|
|
|
|
---
|
|
|
|
## What NOT to Do
|
|
|
|
- Do not commit `config/user.yaml`, `config/notion.yaml`, `config/email.yaml`, `config/adzuna.yaml`, or any `config/integrations/*.yaml` — all are gitignored
|
|
- Do not commit `staging.db`
|
|
- Do not add `torch`, `bitsandbytes`, `transformers`, or `sentence-transformers` to the main environment
|
|
- Do not add `Co-Authored-By:` or AI-attribution lines to commit messages
|
|
- Do not force-push to `main`
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
Open an issue on the repository with the `question` label. Include:
|
|
- Your OS and Docker version
|
|
- The `inference_profile` from your `config/user.yaml`
|
|
- Relevant log output from `make logs`
|