CONTRIBUTING.md

Contributing to SQL Storage Adapter

Thank you for your interest in contributing to SQL Storage Adapter! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

By participating in this project, you agree to abide by our code of conduct: be respectful, inclusive, and constructive in all interactions.

How to Contribute

Reporting Issues

1. Check existing issues to avoid duplicates
2. Use issue templates when available
3. Provide clear reproduction steps
4. Include relevant environment information:
   • Node.js version
   • Operating system
   • Database versions
   • Package version

Suggesting Features

1. Open a discussion first for major features
2. Explain the use case and benefits
3. Consider backward compatibility
4. Provide examples of how it would work

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Update documentation as needed
7. Commit with clear messages
8. Push to your fork
9. Open a Pull Request

Development Setup

Prerequisites

• Node.js 18+
• pnpm 8+
• Git

Local Development

# Clone the repository
git clone https://github.com/framersai/sql-storage-adapter.git
cd sql-storage-adapter

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Generate API documentation
npm run docs

# View coverage report
npm run coverage:view

# Lint code
npm run lint

# Type check
npm run typecheck

Testing with Different Adapters

# Test PostgreSQL adapter
DATABASE_URL=postgresql://user:pass@localhost/test pnpm test

# Test better-sqlite3
STORAGE_ADAPTER=better-sqlite3 pnpm test

# Test sql.js
STORAGE_ADAPTER=sqljs pnpm test

Project Structure

sql-storage-adapter/
├── src/
│   ├── adapters/           # Adapter implementations
│   │   ├── betterSqliteAdapter.ts
│   │   ├── postgresAdapter.ts
│   │   ├── sqlJsAdapter.ts
│   │   └── capacitorSqliteAdapter.ts
│   ├── utils/              # Utility functions
│   ├── types.ts            # TypeScript definitions
│   ├── resolver.ts         # Adapter resolution logic
│   └── index.ts            # Main exports
├── tests/                  # Test files
├── docs/                   # Additional documentation
└── package.json

Coding Standards

TypeScript

• Use TypeScript for all source code
• Maintain strict type safety
• Document complex types
• Avoid any types

Code Style

• Use 2 spaces for indentation
• Use semicolons
• Use single quotes for strings
• Follow existing patterns in the codebase

Documentation

• Document all public APIs with JSDoc
• Include examples in documentation
• Update README for user-facing changes
• Add inline comments for complex logic

Testing

• Write tests for new features
• Maintain test coverage above 80%
• Test error conditions
• Test across different adapters

Adding a New Adapter

1. Create adapter file in src/adapters/
2. Implement the StorageAdapter interface
3. Add capability flags appropriately
4. Update resolver.ts to include the adapter
5. Add tests for the adapter
6. Document pros/cons in README
7. Update TypeScript definitions if needed

Example adapter structure:

export class MyAdapter implements StorageAdapter {
  public readonly kind = 'my-adapter';
  public readonly capabilities = new Set(['transactions', 'persistence']);

  public async open(options?: StorageOpenOptions): Promise<void> {
    // Implementation
  }

  // ... implement other required methods
}

Commit Messages

Follow conventional commits format:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• test: Test additions or changes
• refactor: Code refactoring
• perf: Performance improvements
• chore: Maintenance tasks

Examples:

feat: add streaming support for PostgreSQL adapter
fix: handle connection timeout in resolver
docs: update README with Capacitor examples

Release Process

Releases are automated through GitHub Actions when a new release is published:

Manual Release Steps

1. Update version in package.json following semantic versioning:

   • MAJOR: Breaking changes (e.g., 1.0.0 → 2.0.0)
   • MINOR: New features, backward compatible (e.g., 1.0.0 → 1.1.0)
   • PATCH: Bug fixes, backward compatible (e.g., 1.0.0 → 1.0.1)

2. Update CHANGELOG.md with:

   • Version number and date
   • Added features
   • Changed functionality
   • Deprecated features
   • Removed features
   • Fixed bugs
   • Security updates

3. Create and merge PR:

   git checkout -b release/v1.2.3
   # Update version and changelog
   git commit -m "chore: prepare release v1.2.3"
   git push origin release/v1.2.3
   # Create PR and merge to main

4. Tag and publish release:

   git checkout main
   git pull origin main
   git tag -a v1.2.3 -m "Release v1.2.3"
   git push origin v1.2.3

5. Create GitHub Release:

   • Go to GitHub Releases
   • Click "Create a new release"
   • Select the tag (v1.2.3)
   • Add release notes from CHANGELOG
   • Publish release

6. Automated Publishing:

   • GitHub Actions will automatically:
     • Run tests
     • Build the package
     • Publish to NPM
     • Deploy documentation to GitHub Pages
     • Create release assets

Local Testing Before Release

# Build and test locally
npm run build
npm test

# Create a tarball to inspect package contents
npm pack

# Test the package locally in another project
npm install /path/to/framers-sql-storage-adapter-1.2.3.tgz

Getting Help

• Open an issue for bugs
• Start a discussion for questions
• Check existing documentation
• Review closed issues for solutions

License

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

Acknowledgments

Thank you to all contributors who help make this project better!