# Contributing to Zacatl I appreciate your interest in contributing! This guide will help you get started with development, testing, and submitting changes. ## Getting Started ### Prerequisites - **Node.js**: 24.14.0+ - **npm**: 11.0.0+ - **Git**: latest stable ### Setup 1. **Clone the repository:** ```bash git clone https://github.com/sentzunhat/zacatl.git cd zacatl ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Verify setup:** ```bash npm run type:check npm run lint npm test ``` ### Development Workflow ```bash # Watch mode for development npm run build:watch # TypeScript compilation npm run test:watch # Run tests and watch for changes # In another terminal: npm run lint # ESLint check npm run type:check # TypeScript type checking ``` --- ## Standards & Guidelines All code must follow the standards documented in [docs/guidelines/](../docs/guidelines/): - **Code Style**: [code-style.md](../docs/guidelines/code-style.md) — Formatting, naming, language rules - **Architecture**: [architecture.md](../docs/guidelines/architecture.md) — Folder structure, layering, DI patterns - **Testing**: [testing.md](../docs/guidelines/testing.md) — Test structure, naming, framework setup - **Documentation**: [documentation.md](../docs/guidelines/documentation.md) — Comments, JSDoc, changelog - **Git Workflow**: [git-workflow.md](../docs/guidelines/git-workflow.md) — Commits, versioning, PRs ### Quick Checklist Before committing code: - ✅ Naming follows conventions (PascalCase classes, camelCase functions, kebab-case files) - ✅ Code passes linting: `npm run lint` - ✅ TypeScript strict mode: `npm run type:check` - ✅ All new features/fixes include tests - ✅ Tests pass: `npm test` - ✅ File organization matches architecture patterns - ✅ JSDoc added for public APIs - ✅ Commit message follows Conventional Commits format --- ## Making Changes ### 1. Open an issue, then create a branch Always start with an issue — it keeps work traceable and easy to discuss. 1. Open an issue on GitHub describing what you want to change or fix. 2. Create a branch tied to that issue: ```bash git checkout -b issue-// # Examples: git checkout -b issue-42/feat/add-forbidden-error git checkout -b issue-88/fix/handle-null-connections git checkout -b issue-5/docs/update-api-readme ``` Branch prefixes: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`. ### 2. Make Your Changes **Keep changes focused:** One feature or bug fix per PR. **Follow architecture patterns:** - Domain logic stays in `src/service/layers/domain/` - HTTP handlers in `src/service/layers/application/` - Repositories in `src/service/layers/infrastructure/` - External integrations as adapters **Write tests first (TDD recommended):** ```bash # Create test file matching source structure test/unit/my-feature/my-feature.test.ts # Write test, then implement npm run test:watch ``` ### 3. Validate Your Work Run all checks locally: ```bash npm run type:check # Type checking npm run lint # Linting npm run lint:fix # Auto-fix lint issues npm test # All tests npm run test:coverage # Coverage report npm run build # Clean build ``` **Fix any issues before committing.** - When bumping supported runtime versions, update `peerDependencies` in `package.json` and `docs/third-party/README.md`, then run `npm run type:check && npm test`. ### 4. Commit with Conventional Commits Follow [Conventional Commits](https://www.conventionalcommits.org/) format: ``` ():