Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs: upgrade CONTRIBUTING.md with structured contributor guide
Tanner Kocherdfb156fd8181
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7056dc2b..f01303ed 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,6 +1,14 @@-# Contributing+# Contributing to Ix-## Developer Setup (from source)+## Getting Started++### Prerequisites++- Node.js 20++- Java 17+ and sbt+- Docker and Docker Compose++### Local Setup```bashgit clone https://github.com/ix-infrastructure/Ix.git@@ -8,75 +16,108 @@ cd Ix./setup.sh```-### Testing+This installs dependencies, builds the CLI and backend, and starts Docker services.++### Building from Source++```bash+# core-ingestion (parser library, built automatically by ix-cli)+cd core-ingestion+npm ci+npm run build++# ix-cli+cd ../ix-cli+npm ci+npm run build++# memory-layer (Scala backend)+cd ..+sbt memoryLayer/compile+```++### Verify Your Setup```bash# CLI testscd ix-cli && npm test# Backend tests (requires ArangoDB on localhost:8529)-sbt memoryLayer/test+cd .. && sbt memoryLayer/test++# Smoke test (full stack)+./ix-smoke-test.sh```-### Useful Scripts+## Development Workflow-| Script | Purpose |-|--------|---------|-| `./setup.sh` | Full local setup (backend + CLI + hooks) |-| `./scripts/backend.sh up/down/logs/clean` | Manage Docker backend |-| `./scripts/build-cli.sh` | Build the TypeScript CLI |-| `./scripts/connect.sh <dir>` | Connect a project + ingest |-| `./scripts/disconnect.sh <dir>` | Remove project config |+1. Create a branch from `main`+2. Make your changes+3. Run tests locally+4. Open a PR using the pull request template+5. Ensure CI passes — both CLI and backend jobs must be green before merge-## CI/CD Pipeline+## Branch Naming-### CI (`ci.yml`) — runs on every PR and push to main+```+feat/<name>+fix/<name>+docs/<name>+refactor/<name>+test/<name>+ci/<name>+chore/<name>+```++## Commit Format++Use conventional commit prefixes:-| Job | What it does |-|-----|-------------|-| **CLI** | `npm ci` → `npm run build` → `npm test` |-| **Backend** | `sbt compile` → `sbt test` → `sbt memoryLayer/assembly` |+```+feat: New feature+fix: Bug fix+docs: Documentation only+refactor: Code change that neither fixes a bug nor adds a feature+test: Adding or updating tests+ci: CI/CD changes+chore: Maintenance, dependencies, tooling+```-Both jobs run in parallel. PRs must pass both before merging.+Breaking changes: use `feat!:` or `fix!:` prefix.-### Release (`release.yml`) — runs when a version tag is pushed+## Testing-| Step | What it does |-|------|-------------|-| 1. Build JAR | `sbt memoryLayer/assembly` |-| 2. Docker image | Builds + pushes to `ghcr.io/ix-infrastructure/ix-memory-layer:<version>` and `:latest` |-| 3. Build CLI | `npm ci` → `npm run build` → stamps version |-| 4. Package tarballs | Creates `ix-<ver>-{linux-amd64,darwin-amd64,darwin-arm64}.tar.gz` + `windows-amd64.zip` |-| 5. GitHub Release | Creates release with all assets + install instructions |-| 6. Homebrew | Updates `homebrew/ix.rb` with new URL + SHA256, commits to main |+| What changed | Run |+|---|---|+| CLI code | `cd ix-cli && npm test` |+| Backend code | `sbt memoryLayer/test` |+| CLI behavior | `./ix-smoke-test.sh` |+| Any change | Full test suite before opening PR |-### Release Please (`release-please.yml`) — automated versioning+Run smoke tests for any CLI-facing change. Run backend tests for any Scala change.-Runs on every push to main. Reads conventional commit messages and:-- Opens/updates a "Release vX.Y.Z" PR with a changelog-- When that PR is merged, creates the tag → triggers `release.yml`+## CLI Standards-## Releasing a New Version+### Output quality+- Clean, minimal output — no unnecessary verbosity+- Consistent formatting across all commands-Versioning is automated via release-please. You don't pick version numbers or create tags manually.+### Error handling+- No raw stack traces in normal mode+- Use the structured error system (`ix-cli/src/cli/errors.ts`)+- `--debug` may show detailed output-1. Merge PRs to main using conventional commit messages (`feat:`, `fix:`, `chore:`)-2. release-please auto-opens a Release PR with changelog-3. Merge the Release PR when ready to ship-4. Tag is created automatically → full release pipeline runs+### Language consistency+- Follow existing Ix command voice and terminology+- Match output patterns of existing commands-### Commit prefixes+## OSS vs Pro Boundary-| Prefix | Version bump | Example |-|--------|-------------|---------|-| `fix:` | Patch (0.1.0 → 0.1.1) | `fix: parser fails on decorators` |-| `feat:` | Minor (0.1.0 → 0.2.0) | `feat: add ix docker command` |-| `feat!:` or `BREAKING CHANGE:` | Major (0.2.0 → 1.0.0) | `feat!: redesign CLI flags` |-| `chore:`, `docs:`, `refactor:` | No release | `docs: update README` |+This repository contains open-source Ix functionality. Some features are available only in Ix Pro.-### Manual release (if needed)+Contributors must:+- Not reintroduce Pro-only features into this repository+- Not bypass licensing boundaries+- Respect the separation between OSS and Pro functionality-```bash-git tag v0.2.0-git push origin v0.2.0-```+If you're unsure whether a feature belongs in OSS or Pro, ask in your PR.