Contributing to genkitx-posthog

Thank you for your interest in contributing to genkitx-posthog! This document provides guidelines and instructions for contributing.

Code of Conduct

Please be respectful and considerate in all interactions. We are committed to providing a welcoming and inclusive environment for everyone.

Getting Started

Prerequisites

• Node.js >= 18
• pnpm (recommended) or npm
• A PostHog account for testing (free tier works)

Development Setup

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/genkitx-posthog.git
   cd genkitx-posthog
   

2. Install dependencies

   pnpm install
   

3. Build the project

   pnpm build
   

4. Run type checking

   pnpm typecheck
   

Project Structure

genkitx-posthog/
├── src/
│   ├── index.ts      # Main entry point and exports
│   ├── exporter.ts   # PostHogSpanExporter class
│   ├── types.ts      # TypeScript interfaces
│   ├── utils.ts      # Helper functions
│   ├── logger.ts     # Logger abstraction
│   └── version.ts    # Package version constant
├── dist/
│   ├── esm/          # ES Module build output
│   └── cjs/          # CommonJS build output
├── package.json
├── tsconfig.json
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

Making Changes

Branch Naming

• feat/description - New features
• fix/description - Bug fixes
• docs/description - Documentation updates
• refactor/description - Code refactoring

Commit Messages

Follow Conventional Commits:

feat(exporter): add support for custom event properties
fix(types): correct ContextInfo interface documentation
docs(readme): add serverless usage example

Code Style

• Use TypeScript strict mode
• Add JSDoc comments for all public APIs
• Keep functions focused and small
• Prefer explicit types over any
• Use meaningful variable names

Testing Your Changes

1. Type check

   pnpm typecheck
   

2. Build both ESM and CJS

   pnpm build
   

3. Manual testing

   Create a test script that imports from the built package:

   import { getPostHogProcessor } from './dist/esm/index.js';
   
   const processor = getPostHogProcessor({
     apiKey: 'test-key',
     debug: true,
   });
   
   console.log('Processor created successfully');
   

Pull Request Process

1. Create a feature branch

   git checkout -b feat/my-feature
   

2. Make your changes

   • Write clear, documented code
   • Add or update tests if applicable
   • Update documentation if needed

3. Commit your changes

   git add .
   git commit -m "feat(scope): description of change"
   

4. Push to your fork

   git push origin feat/my-feature
   

5. Create a Pull Request

   • Provide a clear description of the changes
   • Reference any related issues
   • Include testing instructions if applicable

PR Checklist

• Code follows the project's style guidelines
• All type checks pass (pnpm typecheck)
• Both ESM and CJS builds succeed (pnpm build)
• Documentation is updated if needed
• CHANGELOG.md is updated for user-facing changes

Reporting Issues

Bug Reports

Please include:

• genkitx-posthog version
• Node.js version
• Genkit version
• Steps to reproduce
• Expected vs actual behavior
• Any relevant error messages or logs

Feature Requests

Please describe:

• The use case or problem you're trying to solve
• Your proposed solution (if any)
• Any alternatives you've considered

Release Process

Releases are managed by maintainers. The process is:

1. Update version in package.json and src/version.ts
2. Update CHANGELOG.md
3. Create a git tag
4. Publish to npm

Questions?

If you have questions about contributing, feel free to:

• Open a GitHub issue with the "question" label
• Check existing issues and discussions

License

By contributing to genkitx-posthog, you agree that your contributions will be licensed under the Apache-2.0 License.