Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

docs: upgrade CONTRIBUTING.md with structured contributor guide

Tanner Kocherdfb156fd8181
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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
```bash
git 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 tests
cd 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.