ruvector/packages/agentic-synth/docs/CONTRIBUTING.md

Contributing to Agentic-Synth

Thank you for your interest in contributing to Agentic-Synth! We welcome contributions from the community.

🌟 Ways to Contribute

• Bug Reports: Report issues and bugs
• Feature Requests: Suggest new features and improvements
• Code Contributions: Submit pull requests
• Documentation: Improve guides, examples, and API docs
• Templates: Share domain-specific schemas
• Testing: Add test coverage
• Examples: Create example use cases

🚀 Getting Started

Prerequisites

• Node.js >= 18.0.0
• npm, yarn, or pnpm
• Git

Development Setup

1. Fork and clone the repository

git clone https://github.com/your-username/ruvector.git
cd ruvector/packages/agentic-synth

2. Install dependencies

npm install

3. Run tests

npm test

4. Build the package

npm run build

5. Run examples

npm run example:customer-support

📝 Development Workflow

Creating a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Making Changes

1. Write your code following our style guide
2. Add tests for new functionality
3. Update documentation as needed
4. Run linting and type checking:

npm run lint
npm run typecheck

Committing Changes

We follow Conventional Commits:

git commit -m "feat: add new generator for medical data"
git commit -m "fix: resolve streaming memory leak"
git commit -m "docs: update API reference"

Commit types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Creating a Pull Request

1. Push your changes:

git push origin feature/your-feature-name

2. Open a pull request on GitHub
3. Fill out the PR template
4. Wait for review

🧪 Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

import { describe, it, expect } from 'vitest';
import { SynthEngine, Schema } from '../src';

describe('SynthEngine', () => {
  it('should generate data matching schema', async () => {
    const synth = new SynthEngine();
    const schema = Schema.define({
      name: 'User',
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' },
      },
    });

    const result = await synth.generate({ schema, count: 10 });

    expect(result.data).toHaveLength(10);
    expect(result.data[0]).toHaveProperty('name');
    expect(result.data[0]).toHaveProperty('age');
  });
});

📚 Documentation

Updating Documentation

Documentation is located in:

• README.md - Main package documentation
• docs/API.md - Complete API reference
• docs/EXAMPLES.md - Usage examples
• docs/INTEGRATIONS.md - Integration guides

Documentation Style

• Use clear, concise language
• Include code examples
• Add type signatures for TypeScript
• Link to related documentation

🎨 Code Style

TypeScript Style Guide

// Use explicit types
function generateData(count: number): Promise<Data[]> {
  // ...
}

// Use async/await instead of promises
async function fetchData() {
  const result = await api.get('/data');
  return result;
}

// Use descriptive variable names
const userSchema = Schema.define({ /* ... */ });
const generatedUsers = await synth.generate({ schema: userSchema, count: 100 });

// Document complex functions
/**
 * Generates synthetic data based on schema
 * @param options - Generation options
 * @returns Generated data with metadata
 */
async function generate(options: GenerateOptions): Promise<GeneratedData> {
  // ...
}

Linting

We use ESLint and Prettier:

npm run lint        # Check for issues
npm run lint:fix    # Auto-fix issues
npm run format      # Format code

🐛 Reporting Bugs

Before Reporting

1. Check if the bug has already been reported
2. Try the latest version
3. Create a minimal reproduction

Bug Report Template

**Description**
A clear description of the bug.

**To Reproduce**
Steps to reproduce the behavior:
1. Initialize with config '...'
2. Call function '...'
3. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**
- Agentic-Synth version:
- Node.js version:
- OS:

**Code Sample**
\`\`\`typescript
// Minimal reproduction code
\`\`\`

**Error Messages**
\`\`\`
Full error messages and stack traces
\`\`\`

💡 Feature Requests

Feature Request Template

**Feature Description**
A clear description of the feature.

**Use Case**
Why this feature would be useful.

**Proposed API**
\`\`\`typescript
// How the API might look
\`\`\`

**Alternatives Considered**
Other approaches you've considered.

**Additional Context**
Any other context or screenshots.

🔍 Code Review Process

What We Look For

• Correctness: Does it work as intended?
• Tests: Are there adequate tests?
• Documentation: Is it well documented?
• Style: Does it follow our style guide?
• Performance: Are there any performance concerns?
• Breaking Changes: Does it break existing APIs?

Review Timeline

• Initial review: 1-3 business days
• Follow-up reviews: 1-2 business days
• Merge: After approval and CI passes

📦 Publishing (Maintainers Only)

Release Process

1. Update version in package.json
2. Update CHANGELOG.md
3. Create git tag
4. Publish to npm:

npm run build
npm test
npm publish

🏆 Recognition

Contributors will be:

• Listed in package.json contributors
• Mentioned in release notes
• Featured in project README

📞 Getting Help

• Discord: Join our community
• GitHub Discussions: Ask questions
• Email: support@ruv.io

📜 Code of Conduct

Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone.

Our Standards

Positive behavior:

• Using welcoming and inclusive language
• Being respectful of differing viewpoints
• Gracefully accepting constructive criticism
• Focusing on what is best for the community

Unacceptable behavior:

• Trolling, insulting/derogatory comments
• Public or private harassment
• Publishing others' private information
• Other conduct which could reasonably be considered inappropriate

Enforcement

Violations may be reported to support@ruv.io. All complaints will be reviewed and investigated.

📄 License

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

---

Thank you for contributing to Agentic-Synth! 🎉