diff --git a/.gitignore b/.gitignore index 3a08e89..e17fb8b 100644 --- a/.gitignore +++ b/.gitignore @@ -25,6 +25,20 @@ tests/*.sh # Docker build output docker/out/ +# Agent/IDE artifacts +.env.lichyflow +.lichyflow/ +.reasonix/ +lichyflow.yaml +doc +5 +closed +combinedScore +handleType +sourceRanks +sourceScores +true + # PHP extension build artifacts php-ext/autom4te.cache/ php-ext/build/ diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 0000000..653e59f --- /dev/null +++ b/docs/workflow.md @@ -0,0 +1,357 @@ +# Workflow: Issue → Feature Branch → Implementation → Code Review → PR → CI → Merge + +This document describes the complete workflow for handling issues in the +[crazy-goat/php-zvec](https://github.com/crazy-goat/php-zvec) repository +using `gh` and `git`. + +--- + +## 1. Browse Open Issues + +```bash +# List open issues (title, number, labels) +gh issue list --state open --limit 30 + +# View a specific issue (description, labels, state) +gh issue view --json title,body,labels,state +``` + +**Criteria for selecting the most impactful issue:** +- Issues labeled `enhancement`, `bug`, `good-first-issue` +- Issues about stability, memory leaks, data correctness +- Issues blocking other tasks +- Issues most relevant to users (documentation, API coverage) + +--- + +## 2. Create a Fresh Feature Branch + +```bash +# Make sure you're on main with the latest changes +git checkout main +git pull origin main + +# Create a feature branch +git checkout -b feat/issue-- +``` + +**Branch naming convention:** +- `feat/issue--` — new feature +- `fix/issue--` — bug fix +- `docs/issue--` — documentation +- `test/issue--` — test migration or additions + +--- + +## 3. Research Before Implementation + +Before coding, verify the API against reference implementations: + +1. **Check zvec documentation**: https://zvec.org/en/docs/ +2. **Check Node.js API**: https://zvec.org/api-reference/nodejs/ for reference +3. **Check Python SDK** in `zvec/python/zvec/` for actual implementation details +4. **Check C++ headers** in `zvec/src/include/zvec/db/` to verify what's supported + +--- + +## 4. Implement the Change + +```bash +# Edit files, then commit and push +git add -A +git commit -m "feat: implement (closes #)" +git push origin feat/issue-- +``` + +**Commit message convention:** +- Type: `feat`, `fix`, `docs`, `refactor`, `ci`, `test`, `chore` +- Scope: optional, e.g. `(ffi)`, `(php)`, `(build)`, `(docs)` +- Reference to issue: `(closes #)` or `(refs #)` + +--- + +## 5. Code Review via Subagent + +After implementation, run a code review using a subagent (separate agent with +its own context). The subagent checks: + +- Alignment with project structure (PSR-4, FFI patterns, class naming) +- Type correctness and signatures (PHP 8.1+, full type declarations) +- Error handling (FFI status checks, exception propagation) +- Memory management (C string freeing, handle ownership) +- Coding style (see `AGENTS.md` conventions) +- Test coverage (`.phpt` test required for every feature) +- API compatibility with Node.js/Python SDKs + +```bash +# The subagent receives a task like: +# "Code review the changes in files: . +# Check: type correctness, error handling, memory leaks, +# missing tests, outdated documentation. +# List all issues to fix." +``` + +--- + +## 6. Fix Issues Found in Code Review + +```bash +# For each problem found: +# 1. Apply the fix +# 2. Commit with a descriptive message +git add -A +git commit -m "fix: " +git push origin feat/issue-- +``` + +**All issues must be fixed – even the least significant ones.** + +--- + +## 7. Repeat Code Review + +After fixing, invoke the subagent for another code review. + +Repeat steps 5→6 until the subagent reports no issues. + +> **Acceptance criteria:** The subagent responds: "Code looks good, no issues +> to fix." + +--- + +## 8. Build and Test Locally + +Before opening a PR, verify that the project builds and all tests pass: + +### If C++ changes were made (FFI layer): + +```bash +# Build zvec C++ library (skips if already built for this version) +./build_zvec_lib.sh v0.4.0 + +# Build FFI shared library +./build_ffi.sh +``` + +### If only PHP changes were made: + +The FFI shared library must already exist. If not, run `./build_zvec.sh`. + +### Run all tests: + +```bash +# Run all .phpt tests +php run-tests.php tests/ + +# Run specific test file +php run-tests.php tests/test_.phpt + +# Run with verbose output +php run-tests.php -v tests/ +``` + +> **Note:** If you see database errors, clean up stale test directories: +> ```bash +> ls test_dbs/ +> rm -rf test_dbs/*/ +> ``` + +### Verify test databases cleaned up: + +```bash +ls test_dbs/ +# Should be empty (except .gitignore) +``` + +**Only open the PR when all tests pass locally.** + +--- + +## 9. Update CHANGELOG.md + +```bash +# Edit CHANGELOG.md: +# - Add entry under [Unreleased] section +# - Follow Keep a Changelog format (https://keepachangelog.com/en/1.1.0/) +# - Use appropriate section: Added, Changed, Fixed, Removed, Deprecated +# - Include issue number, e.g. (#123) +``` + +--- + +## 10. Create a Pull Request + +```bash +# Create a PR from the feature branch to main +gh pr create \ + --title "feat: (closes #)" \ + --body "## Description + +Closes # + +## Changes + +- + +## Testing + +- [ ] Builds locally (FFI, PHP) +- [ ] All .phpt tests pass +- [ ] No test database leftovers + +## Code Review + +- [ ] Passed subagent code review +- [ ] All review comments addressed" \ + --base main \ + --assignee @me +``` + +> **Note:** If you don't use `gh`, create the PR manually via GitHub UI. + +--- + +## 11. Wait for CI + +```bash +# Check PR status +gh pr view --json statusCheckRollup + +# Wait for all checks to finish +gh pr checks --watch +``` + +CI workflow (`.github/workflows/build.yml`) runs: + +1. **setup-zvec** — builds the zvec C++ library from source or downloads pre-built +2. **build-ext** — builds the PHP extension (`php-ext/`) and runs tests +3. **build-ffi** — builds the FFI shared library (`ffi/`) and runs PHP FFI tests + +> **Note:** The CI workflow triggers on pull requests to `main`, but only for +> builds from the same repository (not forks), due to the `if` condition: +> `github.event.pull_request.head.repo.full_name == github.repository` + +--- + +## 12. Handle CI Failures + +If CI fails: + +```bash +# 1. See which checks failed +gh pr checks + +# 2. View logs +gh run view --log --job + +# 3. Fix the issues locally +# 4. Run code review via subagent again (repeat steps 5-7) +# 5. Run tests locally +php run-tests.php tests/ + +# 6. Commit the fixes +git add -A +git commit -m "fix: " +git push origin feat/issue-- + +# 7. Wait for CI to re-run +gh pr checks --watch +``` + +**Repeat until all CI checks pass.** + +--- + +## 13. Merge PR and Close Issue + +```bash +# Merge PR (squash merge recommended for clean history) +gh pr merge --squash --delete-branch + +# Close the issue (automatic if commit contains "closes #") +# Alternatively: +gh issue close +``` + +--- + +## 14. Switch Back to main + +```bash +git checkout main +git pull origin main +``` + +Done. Ready to start the next cycle from step 1. + +--- + +## Quick Reference – Full Cycle + +```bash +# 1. Pick an issue +gh issue list --state open --limit 30 +gh issue view + +# 2. Feature branch +git checkout main && git pull origin main +git checkout -b feat/issue-- + +# 3. Research API (Node.js, Python, C++) +# https://zvec.org/api-reference/nodejs/ + +# 4. Implementation +# ... coding ... +git add -A && git commit -m "feat: implement (closes #)" +git push origin feat/issue-- + +# 5. Code Review (subagent) +# ... fix issues ... (repeat until clean) + +# 6. Build and test locally +./build_zvec_lib.sh v0.4.0 +./build_ffi.sh +php run-tests.php tests/ + +# 7. Update CHANGELOG.md + +# 8. PR +gh pr create --title "feat: (closes #)" --body "..." --base main + +# 9. CI +gh pr checks --watch +# ... if failures → fix, code review, push → wait for CI (repeat) + +# 10. Merge +gh pr merge --squash --delete-branch +gh issue close + +# 11. Switch back to main +git checkout main && git pull origin main +``` + +--- + +## Notes + +- **gh** must be configured and authenticated (`gh auth status`). +- This project has **no linting/static analysis pipeline** (no php-cs-fixer, + phpstan, psalm). Follow conventions manually — see `AGENTS.md`. +- The CI builds zvec from source only once per workflow run and caches it + as an artifact for downstream jobs (ext + ffi). +- Pre-built zvec artifacts are stored in GitHub Releases under the + `zvec-build-v0.4.0` release tag and downloaded by CI to avoid rebuilding + from source on every PR. +- Test databases are created in `test_dbs/` (git-ignored). Always clean up + after test runs: `rm -rf test_dbs/*/` +- Keep feature branches short-lived. If a rebase is needed: + ```bash + git fetch origin main + git rebase origin/main + git push --force-with-lease origin feat/issue-- + ``` +- Code review via subagent runs locally – the subagent has access to + read/write/edit/bash tools. Give it clear instructions on what to check. +- For release workflow (tagging, CHANGELOG, version bump), see the + "Release Workflow" section in `AGENTS.md`. Never push tags — user + pushes manually.