Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (101 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

141 lines (101 loc) · 4.87 KB
Raw

Contributing to @lousho/build-ai-agent

Thank you for your interest in contributing to the Build AI Agent SDK! This document provides guidelines and instructions for contributing.

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

Getting Started

Prerequisites

  • Node.js >= 22.19.0
  • npm, pnpm, or yarn

Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/agent-sdk.git
cd agent-sdk
  3. Install dependencies: 
    npm install
  4. Build the project: 
    npm run build
  5. Run tests: 
    npm test

Development Workflow

Making Changes

  1. Create a new branch:

    git checkout -b feature/your-feature-name

  2. Make your changes

  3. Ensure your code passes all checks:

    npm run typecheck  # Type checking
npm run typecheck:tests  # The test files are type-checked too
npm run lint       # Linting
npm run test:coverage && npm run fallow  # Dead code, duplication, complexity (must exit 0)
npm test           # Tests
npm run build      # Build

    Changes to the Docker sandbox, its network egress, the credential broker or the docker deploy adapter also have real-daemon tests, npm run test:docker (*.docker.test.ts, not part of npm test). They skip without a Docker daemon (the egress cases also skip on Docker Desktop and rootless Docker, where egress is refused by design), so they run in CI's compat job on Linux; set LOUSHO_DOCKER_TESTS=1 to make a missing daemon fail the run instead.

  4. Commit your changes with a descriptive commit message

  5. Push to your fork and create a pull request

Lint rules

npm run lint runs with --max-warnings 0; no-explicit-any, no-unused-vars and ban-ts-comment are errors (prefix an unused parameter an interface requires with _). When a real type is not possible, use a targeted // eslint-disable-next-line <rule> -- <reason> on that one line, never a file- or directory-wide disable, a rule turned off in the config or a new ignores entry. In tests, a value of the wrong type passed on purpose gets // @ts-expect-error -- <reason>, and a partial mock is cast to the type it stands in for (as Partial<T> as T when it lacks a required member).

Code Style

  • Use TypeScript for all code
  • Follow existing code patterns and conventions
  • Add JSDoc comments for public APIs
  • Keep functions small and focused
  • Write meaningful variable and function names

Testing

  • Write tests for new features
  • Ensure all existing tests pass
  • Aim for good test coverage
  • Tests are located alongside source files with .test.ts extension
  • npm run pack-smoke installs the tarball built from your checkout into a fresh project and exercises it. npm run registry-smoke does the same for what is published on npm: npm create lousho-agent, the generated project's tests and type check, lousho doctor, every export in ESM and CJS, and lousho studio. Run it right after a publish (-- --version <semver|dist-tag> picks the version; -- --live adds one real OpenRouter turn and needs OPENROUTER_API_KEY).

Documentation

  • Update README.md if adding new features
  • Add JSDoc comments for new public APIs
  • Update CHANGELOG.md for notable changes

Public API changes

Every exports entry of the package has a checked-in API report under api/ (api/index.api.md, api/executor.api.md, ..., one api/<subpath>.api.md per subpath), generated by @microsoft/api-extractor from the built declarations. If your change adds, removes or alters anything public, run npm run build && npm run api:update and commit the report diffs with your change - the reviewer reads that diff to see exactly how the public surface moved. CI runs npm run api:check after the build and fails when the checked-in reports are out of date. Types a public signature uses but the entry point does not export are recorded in the report (ae-forgotten-export), so they are visible too.

Pull Request Process

  1. Ensure your PR includes:

    • Clear description of changes
    • Tests for new functionality
    • Updated documentation if needed

  2. Your PR will be reviewed by maintainers

  3. Address any feedback

  4. Once approved, your PR will be merged

Reporting Issues

When reporting issues, please include:

  • A clear and descriptive title
  • Steps to reproduce the issue
  • Expected behavior
  • Actual behavior
  • Node.js version
  • Operating system
  • Any relevant code snippets or error messages

Feature Requests

Feature requests are welcome! Please:

  • Check existing issues to avoid duplicates
  • Provide a clear use case
  • Explain why this feature would be useful

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Questions?

Feel free to open an issue for any questions about contributing.