ruvector/docs/CONTRIBUTING.md

Contributing to RuVector

Thank you for your interest in contributing to RuVector!

Development Setup

1. Clone the Repository

git clone https://github.com/ruvnet/ruvector.git
cd ruvector

2. Install Dependencies

cd npm
npm install

3. Install Git Hooks (Recommended)

We provide git hooks that automatically keep package-lock.json in sync:

./scripts/install-hooks.sh

This will:

• Automatically run npm install when you modify package.json
• Stage the updated package-lock.json automatically
• Prevent CI/CD failures due to lock file mismatches

Package Management

Adding Dependencies

When adding new dependencies to any package:

cd npm/packages/<package-name>
npm install <dependency>

Important: Always commit the updated package-lock.json with your changes!

Manual Lock File Sync

If you forget to sync the lock file, you can use our helper script:

./scripts/sync-lockfile.sh

Common Issues

CI/CD Fails with "Lock file out of sync"

Problem: npm ci fails with:

npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync

Solution:

cd npm
npm install
git add package-lock.json
git commit -m "fix: Sync package-lock.json"
git push

Or use the automated script:

./scripts/sync-lockfile.sh

Pre-commit Hook Not Working

If the git hook isn't triggering:

# Reinstall hooks
./scripts/install-hooks.sh

# Verify hook is executable
ls -la .git/hooks/pre-commit

Development Workflow

1. Create a feature branch

   git checkout -b feat/your-feature-name
   

2. Make your changes

   • Write code in the appropriate package
   • Add tests for new features
   • Update documentation

3. Build and test

   cd npm
   npm run build
   npm test
   

4. Commit your changes

   git add .
   git commit -m "feat: Your descriptive commit message"
   

   The pre-commit hook will automatically sync the lock file if needed.

5. Push and create PR

   git push origin feat/your-feature-name
   

Package Structure

ruvector/
├── npm/
│   ├── core/              # @ruvector/core - Native Rust bindings
│   ├── packages/
│   │   ├── ruvector/      # ruvector - Wrapper package
│   │   └── ruvector-extensions/  # ruvector-extensions - Feature extensions
│   └── package-lock.json  # Workspace lock file
├── scripts/
│   ├── sync-lockfile.sh   # Auto-sync lock file
│   ├── install-hooks.sh   # Install git hooks
│   └── ci-sync-lockfile.sh  # CI/CD lock file sync
└── .githooks/
    └── pre-commit         # Pre-commit hook script

Testing

Run All Tests

cd npm
npm test

Test Specific Package

cd npm/packages/ruvector-extensions
npm test

Manual Testing

cd npm/packages/ruvector-extensions/examples
tsx complete-integration.ts

Code Style

• TypeScript: Use strict mode, full type annotations
• Formatting: 2 spaces, semicolons, single quotes
• Comments: JSDoc for public APIs
• Naming: camelCase for variables/functions, PascalCase for classes

Commit Messages

Follow Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Test updates
• chore: - Build/tooling changes

Examples:

feat: Add OpenAI embeddings provider
fix: Resolve CommonJS export issue
docs: Update embeddings API documentation
chore: Sync package-lock.json

Pull Request Process

1. Ensure CI passes

   • All tests pass
   • Build succeeds
   • No linting errors

2. Update documentation

   • README.md if public API changes
   • JSDoc comments for new functions
   • CHANGELOG.md with notable changes

3. Describe your changes

   • Clear PR title and description
   • Reference related issues
   • Include examples if applicable

4. Request review

   • Maintainers will review within 48 hours
   • Address feedback promptly
   • Keep discussion focused and professional

Release Process

Releases are handled by maintainers:

1. Version bump in package.json
2. Update CHANGELOG.md
3. Create git tag
4. Publish to npm
5. Create GitHub release

Questions?

• 📖 Check the documentation
• 🐛 Report bugs in Issues
• 💬 Ask questions in Discussions

License

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