# 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 ```bash # Clone the repository git clone https://github.com/framerslab/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 ```bash # 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: ```typescript export class MyAdapter implements StorageAdapter { public readonly kind = 'my-adapter'; public readonly capabilities = new Set(['transactions', 'persistence']); public async open(options?: StorageOpenOptions): Promise { // 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](https://semver.org/): - **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**: ```bash 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**: ```bash 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 ```bash # 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!