FIRST_CONTRIBUTION.md

First contribution

One-page path from fork to a green PR. Full rules live in CONTRIBUTING.md.

Before you code

1. Read the hook in README.md — Matryca Plumber is Logseq OG (Markdown on disk), not a hosted notes API.
2. Pick work:
   • Good first issues (label good first issue)
   • Tier F Clean Code / Tier G complexity slices — good_first_issues_blueprints.md
3. For architecture debate (v2 Shadow DB), use Discussion #19; for trackable bugs/features, open an issue.

Local setup

git clone https://github.com/MarcoPorcellato/matryca-plumber.git
cd matryca-plumber
make install
cd frontend && npm install && npm run build && cd ..

Requires Python ≥3.12 and Node.js 22 (see pyproject.toml).

Dev loop

make test-fast    # fast pytest loop (~seconds)
make ci           # full gate before PR (format-check + lint + mypy + tests)

Graph changes: never delete id:: lines; respect OCC — see Phase 0–4 in CONTRIBUTING.md.

Open a PR

1. Branch from main.
2. Run make ci locally.
3. User-visible changes: bullet under ## [Unreleased] in CHANGELOG.md.
4. Use the PR template — link Fixes #N or Refs #N.

Merge bar: make check / make ci green on GitHub Actions.

Where to ask

Question	Channel
Bug or feature	GitHub Issue
RFC / design	Discussions
Security	Private advisory — not a public issue
Conduct	marco@matryca.ai — CODE_OF_CONDUCT.md