docs(pry): add CONTRIBUTING.md with workflow, remotes, recovery guide
Documents: - Branch model (main + feat/fix/chore/refactor/docs/phase) - Conventional Commits via 'make commit' - Sync workflow (pull --rebase upstream main) - Remotes: upstream (canonical) + legacy-mirror - Pre-push checklist (lint, typecheck, test, security, ci) - Test environment requirements (Postgres, Redis, FlareSolverr) - Disaster recovery via 'git bundle --all' - Reference to archived Phase-0 work (phase0-fixes-archive branch)
This commit is contained in:
parent
c47816c34e
commit
4344ee5987
1 changed files with 202 additions and 0 deletions
202
CONTRIBUTING.md
Normal file
202
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,202 @@
|
||||||
|
<!--
|
||||||
|
SPDX-License-Identifier: MIT
|
||||||
|
Copyright (c) 2026 Rug Munch Media LLC
|
||||||
|
Part of Pry — https://git.rugmunch.io/RugMunchMedia/pryscraper
|
||||||
|
Licensed under MIT. See LICENSE.
|
||||||
|
-->
|
||||||
|
|
||||||
|
# Contributing to Pry
|
||||||
|
|
||||||
|
> Multi-source crypto intelligence crawler. Production-grade FastAPI + Python 3.12.
|
||||||
|
|
||||||
|
## TL;DR
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout main && git pull --rebase upstream main
|
||||||
|
git checkout -b feat/my-change
|
||||||
|
# …make changes…
|
||||||
|
make lint test # pre-push gate
|
||||||
|
make commit # conventional commits via commitizen
|
||||||
|
git push upstream feat/my-change
|
||||||
|
# Open a PR on Forgejo (git.rugmunch.io/RugMunchMedia/pryscraper)
|
||||||
|
# After review: merge to main, push back to upstream
|
||||||
|
```
|
||||||
|
|
||||||
|
## Repository Model
|
||||||
|
|
||||||
|
This repo follows the **single-tenant branch-PR pattern** — a small team that
|
||||||
|
treats `feat/*` branches as the unit of review, merged directly to `main` after
|
||||||
|
CI passes and at least one approval.
|
||||||
|
|
||||||
|
### Branches
|
||||||
|
|
||||||
|
| Branch | Purpose |
|
||||||
|
|-----------------------|--------------------------------------------------|
|
||||||
|
| `main` | Production-ready. Protected. Forgejo-mirrored. |
|
||||||
|
| `feat/<scope>` | New feature or capability. |
|
||||||
|
| `fix/<scope>` | Bug fix. |
|
||||||
|
| `chore/<scope>` | Tooling, deps, formatting, non-functional. |
|
||||||
|
| `refactor/<scope>` | Code restructure, no behavior change. |
|
||||||
|
| `docs/<scope>` | Documentation only. |
|
||||||
|
| `phase<N>-<scope>` | Multi-commit initiative (e.g. `phase0-infra`). |
|
||||||
|
|
||||||
|
### Commit Convention
|
||||||
|
|
||||||
|
We use **Conventional Commits** enforced by `commitizen` + `commitlint`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make commit # interactive — prompts for type, scope, message
|
||||||
|
```
|
||||||
|
|
||||||
|
Allowed types: `feat`, `fix`, `docs`, `refactor`, `style`, `test`, `chore`,
|
||||||
|
`ops`, `security`, `ci`, `build`, `perf`, `revert`.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
feat(api): expose /metrics endpoint as Prometheus text format
|
||||||
|
fix(pry): JWT fail-closed, fix gdpr_real SQL imports
|
||||||
|
docs(pry): add 2026-Q3 production audit + plan
|
||||||
|
ops(deploy): pin playwright>=1.50.0, add healthcheck stage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Sync Workflow
|
||||||
|
|
||||||
|
### Daily sync
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout main
|
||||||
|
git pull --rebase upstream main # rebase, never merge
|
||||||
|
git push upstream main # fast-forward only
|
||||||
|
```
|
||||||
|
|
||||||
|
`pull.rebase=true` is set in `.git/config` — this is the default behavior.
|
||||||
|
|
||||||
|
### Working on a feature
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git fetch upstream
|
||||||
|
git checkout -b feat/my-change upstream/main
|
||||||
|
# work, commit, repeat
|
||||||
|
git push upstream feat/my-change # push branch to canonical
|
||||||
|
```
|
||||||
|
|
||||||
|
### After PR merged (or direct merge in single-tenant flow)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout main
|
||||||
|
git pull --rebase upstream main # picks up the merge
|
||||||
|
git branch -d feat/my-change # delete local (use -D if not merged upstream)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Remotes
|
||||||
|
|
||||||
|
| Remote | URL | Role |
|
||||||
|
|-----------------|---------------------------------------------------|------------------------------------|
|
||||||
|
| `upstream` | `root@talos:/srv/work/repos/pryscraper/.git` | **Canonical** — Forgejo clone. |
|
||||||
|
| `legacy-mirror` | `root@talos:/srv/git/pry.git` | Legacy bare repo. Sync only. |
|
||||||
|
|
||||||
|
`origin` is **not configured** — there is no single-host Forgejo SSH endpoint
|
||||||
|
reachable from Cinnabox. Always push to `upstream`.
|
||||||
|
|
||||||
|
To add an external mirror (GitHub/GitLab/HuggingFace), request credentials via
|
||||||
|
gopass and add the remote under a descriptive name (`github`, `gitlab`, `hf`).
|
||||||
|
See `/srv/work/repos/fleet-infra/` for the established pattern.
|
||||||
|
|
||||||
|
## Pre-Push Checklist
|
||||||
|
|
||||||
|
Before pushing any branch:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
make lint # ruff check + format check
|
||||||
|
make typecheck # mypy strict
|
||||||
|
make test # pytest (see "Test Environment" below)
|
||||||
|
make security # bandit + gitleaks (runs in CI; optional locally)
|
||||||
|
make ci # all of the above
|
||||||
|
```
|
||||||
|
|
||||||
|
CI is defined in `.forgejo/workflows/ci.yml` and runs on every push.
|
||||||
|
|
||||||
|
## Test Environment
|
||||||
|
|
||||||
|
Some tests depend on external services:
|
||||||
|
|
||||||
|
| Service | Required by | How to run |
|
||||||
|
|-------------|----------------------------------------------------|---------------------------|
|
||||||
|
| Postgres | `tests/test_*_db*.py`, alembic migrations | `docker compose up postgres` |
|
||||||
|
| Redis | `tests/test_*_cache*.py` | `docker compose up redis` |
|
||||||
|
| FlareSolverr| `tests/test_anti_detection.py` | `docker compose up flaresolverr` |
|
||||||
|
|
||||||
|
Tests that require services will skip (or return 503 on `/ready`) without them.
|
||||||
|
This is expected — the production `/ready` endpoint is intentionally strict.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Quick smoke (no services required)
|
||||||
|
PRY_JWT_SECRET=test-secret pytest tests/test_x402_mcp_spec.py tests/test_api_surface_snapshot.py tests/test_compliance.py -q
|
||||||
|
```
|
||||||
|
|
||||||
|
## Disaster Recovery
|
||||||
|
|
||||||
|
Before any risky operation (`reset --hard`, `rebase`, large `cherry-pick`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git bundle create /tmp/pry-backup-$(date +%Y%m%d-%H%M%S).bundle --all
|
||||||
|
```
|
||||||
|
|
||||||
|
To restore from a bundle:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone /tmp/pry-backup-XXX.bundle /tmp/pry-restored
|
||||||
|
```
|
||||||
|
|
||||||
|
The bundle includes **every ref** — branches, tags, stashes-as-commits,
|
||||||
|
remote-tracking branches. To restore just `main`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone -b main /tmp/pry-backup-XXX.bundle /tmp/pry-restored
|
||||||
|
```
|
||||||
|
|
||||||
|
## Working with Archived Work
|
||||||
|
|
||||||
|
Phase-0 work (the 5 commits originally on `feat/metrics-endpoint` local-only)
|
||||||
|
was preserved during the 2026-Q3 reorg. To recover it:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git log phase0-fixes-archive # 5 commits: JWT, tiers, cli, deps, tests
|
||||||
|
git format-patch 47875ae^..1698a47 -o /tmp/patches/
|
||||||
|
# Apply individually with `git am` on a fresh branch
|
||||||
|
```
|
||||||
|
|
||||||
|
Most of this work has since been superseded by the canonical Forgejo main
|
||||||
|
(`refs/heads/main` at git.rugmunch.io), but the patches remain useful as a
|
||||||
|
reference for the original intent and as a starting point for re-applied
|
||||||
|
fixes on the new module layout (post `refactor/dedup-root-modules`).
|
||||||
|
|
||||||
|
Pre-Phase-0 WIP (the 4589-insertion initial WIP) is preserved on the
|
||||||
|
`pre-phase0-wip-archive` branch from the same commit base.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Dual-licensed:
|
||||||
|
|
||||||
|
- **MIT** for core modules (any PR welcome).
|
||||||
|
- **BSL 1.1** for stealth/anti-detection code (listed in `LICENSE-BSL-STEALTH`).
|
||||||
|
Only Rug Munch Media LLC can modify BSL files. PRs that touch BSL files will
|
||||||
|
be rejected.
|
||||||
|
|
||||||
|
When contributing, you agree your MIT-licensed contributions may be relicensed
|
||||||
|
by Rug Munch Media LLC under compatible terms.
|
||||||
|
|
||||||
|
## Code of Conduct
|
||||||
|
|
||||||
|
Be precise, be kind. Cite file:line when reviewing. Prefer surgical commits
|
||||||
|
over sweeping refactors.
|
||||||
|
|
||||||
|
## Further Reading
|
||||||
|
|
||||||
|
- `AGENTS.md` — repo contract, owners, commands, dependencies
|
||||||
|
- `ARCHITECTURE.md` — module layout, data flow, deployment
|
||||||
|
- `STATUS.md` — current sprint status (update before each commit)
|
||||||
|
- `PLAN.md` — roadmap and active initiatives
|
||||||
|
- `AUDIT-2026-Q3.md` — production readiness gap analysis
|
||||||
|
- `../standards/CONVENTIONS.md` — fleet-wide conventions
|
||||||
|
- `../standards/TOOLCHAIN.md` — tool inventory
|
||||||
Loading…
Add table
Add a link
Reference in a new issue