Docs/Testing and pull requests

Contributing

Testing and pull requests

Create a focused branch, run the checks appropriate to your change, and open a reviewable pull request.

Sync your fork

terminal

git checkout main
git fetch upstream
git merge --ff-only upstream/main
git push origin main

Create a focused branch

Choose a short description and a prefix that communicates the type of change.

feat/short-description: a new user-facing capability.

fix/short-description: a bug fix.

chore/short-description: maintenance, tooling, dependencies, or repository housekeeping.

refactor/short-description: an internal change that preserves behavior.

test/short-description: test additions or improvements.

docs/short-description: documentation-only changes.

terminal

git checkout -b feat/short-description

Required checks

Every change should pass the repository's type, lint, build, and unit-test checks.

terminal

npm run typecheck
npm run lint
npm run build
npm run test:run

Change-specific checks

Run npm run test:package for CLI, package exports, packaging, or generated-project workflow changes.

Run npm run test:core with DATABASE_URL configured for database-backed core behavior.

Run npm run test:fleet with DATABASE_URL configured for fleet behavior.

Add a focused test under tests/manual/ when an algorithm or provider behavior benefits from realistic end-to-end verification.

Redis is not required for default unit tests or PostgreSQL-only development.

Live smoke tests

Before releasing, or after changing a critical Grafter, ingestion, Fleet, crawler, or lifecycle workflow, run the minimal live smoke suite.

The suite uses the root .env; its basic chat, graph building, queue, and Fleet checks call OpenAI. Queue and recall-cache coverage runs when REDIS_URL is configured.

Minimal live smoke suite

npm run live-smoke:smoke

Live smoke report

The --write-doc option saves a Markdown report containing timings, answers, drift scores, node counts, queue metrics, and estimated token usage.

See tests/manual/live-smoke/README.md for individual suite commands and reporting options.

Markdown report

npm run live-smoke:smoke -- --write-doc

Formatting, tests, and documentation

Add or update automated tests whenever behavior changes.

Update public documentation when behavior, configuration, or usage changes.

Update the changelog only when required by the release process.

The repository does not currently define a formatter script. Do not invent a formatter command; use typecheck and lint as the enforced style checks until one is added.

Keep provider-specific tests close to adapter behavior and do not require provider credentials for unrelated test suites.

Commit and push

Use concise conventional-style commit and pull-request titles such as feat: add provider adapter, fix: avoid duplicate ingestion, or docs: clarify migration setup.

terminal

git add <changed-files>
git commit -m "feat: short description"
git push -u origin feat/short-description

Open the pull request

Open the pull request from your fork into mayhemking007/memo-grafter's main branch.

Explain what changed and why.

Link the related issue.

Describe the checks and manual validation you performed.

Mention compatibility considerations, migration requirements, and follow-up work.

Keep the pull request focused on one logical change.

Respond politely and constructively to review feedback.

Open a MemoGrafter pull requestCompare your fork's focused branch with the MemoGrafter main branch.

Merge expectations

Accepted pull requests are expected to be squash-merged so main receives one focused commit. Keep commits understandable during review, but write the pull-request title and description so they can represent the final merged change.