|
| 1 | +# Contributing to GitClaw |
| 2 | + |
| 3 | +Thanks for your interest in contributing to GitClaw! Here's how to get started. |
| 4 | + |
| 5 | +## Getting Started |
| 6 | + |
| 7 | +1. Fork the repository |
| 8 | +2. Clone your fork: |
| 9 | + ```bash |
| 10 | + git clone https://github.com/<your-username>/gitclaw.git |
| 11 | + cd gitclaw |
| 12 | + ``` |
| 13 | +3. Install dependencies: |
| 14 | + ```bash |
| 15 | + npm install |
| 16 | + ``` |
| 17 | +4. Build the project: |
| 18 | + ```bash |
| 19 | + npm run build |
| 20 | + ``` |
| 21 | +5. Run tests: |
| 22 | + ```bash |
| 23 | + npm test |
| 24 | + ``` |
| 25 | + |
| 26 | +## Development Workflow |
| 27 | + |
| 28 | +1. Create a feature branch from `main`: |
| 29 | + ```bash |
| 30 | + git checkout -b feat/my-feature |
| 31 | + ``` |
| 32 | +2. Make your changes in `src/` |
| 33 | +3. Run `npm run build` to verify compilation |
| 34 | +4. Run `npm test` to ensure tests pass |
| 35 | +5. Commit your changes with a clear message |
| 36 | +6. Push and open a pull request |
| 37 | + |
| 38 | +## Project Structure |
| 39 | + |
| 40 | +``` |
| 41 | +src/ |
| 42 | +├── index.ts # CLI entry point |
| 43 | +├── sdk.ts # Core SDK (query function) |
| 44 | +├── exports.ts # Public API surface |
| 45 | +├── loader.ts # Agent config loader |
| 46 | +├── tools/ # Built-in tools (cli, read, write, memory) |
| 47 | +├── voice/ # Voice mode (OpenAI Realtime adapter) |
| 48 | +├── hooks.ts # Script-based hooks |
| 49 | +├── sdk-hooks.ts # Programmatic SDK hooks |
| 50 | +├── skills.ts # Skill expansion |
| 51 | +├── workflows.ts # Workflow metadata |
| 52 | +├── agents.ts # Sub-agent metadata |
| 53 | +├── compliance.ts # Compliance validation |
| 54 | +└── audit.ts # Audit logging |
| 55 | +``` |
| 56 | + |
| 57 | +## Guidelines |
| 58 | + |
| 59 | +- **TypeScript** — all code is written in strict TypeScript |
| 60 | +- **ESM** — the project uses ES modules (`"type": "module"`) |
| 61 | +- **Keep it simple** — avoid over-engineering; minimal dependencies |
| 62 | +- **Test your changes** — add or update tests in `test/` when applicable |
| 63 | +- **One concern per PR** — keep pull requests focused and reviewable |
| 64 | + |
| 65 | +## Commit Messages |
| 66 | + |
| 67 | +Use clear, descriptive commit messages: |
| 68 | + |
| 69 | +- `Add voice mode with OpenAI Realtime adapter` |
| 70 | +- `Fix memory tool path resolution on Windows` |
| 71 | +- `Update SDK query to support abort signals` |
| 72 | + |
| 73 | +## Reporting Issues |
| 74 | + |
| 75 | +- Search existing issues before opening a new one |
| 76 | +- Include reproduction steps, expected vs actual behavior, and your environment (Node version, OS) |
| 77 | + |
| 78 | +## Code of Conduct |
| 79 | + |
| 80 | +Be respectful and constructive. We're all here to build something useful together. |
| 81 | + |
| 82 | +## License |
| 83 | + |
| 84 | +By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE). |
0 commit comments