# Contributing

Set up the Milvus Node.js SDK development environment, run tests, submit a signed-off pull request, and build the docs site.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/reference/contributing/

## Section links

- [Develop and submit a change](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#develop-and-submit-a-change)
- [Code Structure](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#code-structure)
- [Directory Structure](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#directory-structure)
- [Key Files](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#key-files)
- [Documentation](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#documentation)
- [Update Documentation](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#update-documentation)
- [Documentation Structure](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#documentation-structure)
- [Reporting Issues](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#reporting-issues)
- [Bug Reports](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#bug-reports)
- [Feature Requests](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#feature-requests)
- [Code of Conduct](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#code-of-conduct)
- [Getting Help](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#getting-help)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#next-steps)
- [Build and preview the documentation site](https://milvus-io.github.io/milvus-sdk-node/reference/contributing/#build-and-preview-the-documentation-site)

Thank you for your interest in contributing to the Milvus Node.js SDK!

## Develop and submit a change

Use the [repository contribution guide](https://github.com/milvus-io/milvus-sdk-node/blob/main/CONTRIBUTING.md) for development setup, test commands, and the pull request process. It explains how to install the locked dependencies, initialize the pinned protobuf sources, and sign off each commit for DCO.

For SDK changes, run the relevant tests under `test2/` and report the results in your pull request. The [test suite guide](https://github.com/milvus-io/milvus-sdk-node/blob/main/test2/README.md) covers unit tests, server-backed tests, the npm package lifecycle, and the coverage gate.

## Code Structure

### Directory Structure

```plaintext
milvus-sdk-node/
├── milvus/           # Main SDK code
│   ├── grpc/        # gRPC client
│   ├── http/        # HTTP client
│   ├── types/       # TypeScript types
│   └── utils/       # Utilities
├── test2/           # Tests
├── benchmarks/      # Manual performance benchmarks
├── examples/        # Examples
└── docs/           # Documentation
```

### Key Files

- `milvus/MilvusClient.ts`: Main client class
- `milvus/grpc/`: gRPC implementation
- `milvus/http/`: HTTP implementation
- `milvus/types/`: TypeScript type definitions

## Documentation

### Update Documentation

When adding features:

1. Update relevant documentation files
2. Add code examples
3. Update API reference if needed

### Documentation Structure

- `docs/src/content/docs/`: Documentation source files
- Use MDX format
- Include code examples

## Reporting Issues

### Bug Reports

Include:

- SDK version
- Node.js version
- Steps to reproduce
- Expected vs actual behavior
- Error messages/logs

### Feature Requests

Include:

- Use case description
- Proposed solution
- Benefits

## Code of Conduct

Please follow the [Code of Conduct](https://github.com/milvus-io/milvus-sdk-node/blob/main/CODE_OF_CONDUCT.md).

## Getting Help

- [GitHub Issues](https://github.com/milvus-io/milvus-sdk-node/issues)
- [Discussions](https://github.com/milvus-io/milvus-sdk-node/discussions)
- [Milvus Community](https://milvus.io/community)

## Next Steps

- Read [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/)
- Check [API Reference](https://milvus-io.github.io/milvus-sdk-node/api-reference/)
- Explore [Examples & Tutorials](https://milvus-io.github.io/milvus-sdk-node/getting-started/examples-tutorials/)

## Build and preview the documentation site

Install the documentation dependencies separately from SDK dependencies:

```bash
yarn --cwd docs install --frozen-lockfile
npm run doc
npm run doc:dev
```

The site uses Astro/Starlight and writes production output to `docs/out/`. Edit MDX under `docs/src/content/docs/`; `npm run doc` preserves these source files. For production preview, run `npm --prefix docs run preview` after building. Use Node.js 22.23.4 or newer for the current locked Astro version; the documentation toolchain can require a newer runtime than the SDK.

The production build checks internal links and heading fragments against the generated pages and verifies canonical URLs, metadata, and the sitemap.

When releasing, compare the published tag with the last documented version, update guides and API reference, add release notes, and synchronize README compatibility and `llms.txt`. Verify example imports against package exports.
