Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (97 loc) · 3.3 KB

CONTRIBUTING.md

File metadata and controls

132 lines (97 loc) · 3.3 KB

Contributing to SyncVault

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

Getting Started

Prerequisites

  • Node.js 18+
  • npm, yarn, or pnpm
  • Git

Development Setup

  1. Fork and Clone

    git clone https://github.com/your-username/sync-vault-js.git
cd sync-vault-js

  2. Install Dependencies

    npm install

  3. Build the Package

    npm run build

  4. Run the Demo

    npm run demo

    This will start the interactive demo at http://localhost:8000

  5. Run Tests (when available)

    npm test

Testing Your Changes

Using the Demo Application

The demo app in /demo is the best way to test your changes:

  1. Make your changes to the source code
  2. Run npm run build to rebuild
  3. Run npm run demo to see your changes in action
  4. Test various scenarios:
    • Queue requests when offline
    • Process queue when coming online
    • Test retry logic with failing endpoints
    • Verify Dead Letter Queue behavior

Manual Testing Checklist

  • Request queuing works when offline
  • Queue processes when coming online
  • Exponential backoff retry logic works
  • Dead Letter Queue captures failed jobs
  • Events are emitted correctly
  • Storage adapters work (IndexedDB and Memory)
  • Network detection works (online/offline events)
  • Framework integrations work (React, Vue, Angular, Svelte)

Code Style

  • TypeScript: Strict mode, no any types
  • Formatting: Follow existing code style
  • Naming: Use descriptive names, camelCase for variables/functions, PascalCase for classes
  • Comments: Document complex logic and public APIs

Project Structure

src/
├── core/           # Core library logic (framework-agnostic)
├── storage/        # Storage adapters (IndexedDB, Memory)
├── utils/          # Utility functions (retry, backoff)
└── integrations/   # Framework-specific wrappers

Making Changes

Adding Features

  1. Create a feature branch: git checkout -b feature/your-feature-name
  2. Make your changes
  3. Update tests and documentation
  4. Test with the demo app
  5. Submit a pull request

Fixing Bugs

  1. Create a bugfix branch: git checkout -b fix/bug-description
  2. Fix the issue
  3. Add tests if possible
  4. Test with the demo app
  5. Submit a pull request

Documentation

  • Update README.md for user-facing changes
  • Add JSDoc comments for new public APIs
  • Update demo app if adding new features

Pull Request Process

  1. Update Documentation: Ensure README and code comments are updated
  2. Test Thoroughly: Use the demo app to test all scenarios
  3. Write Clear PR Description: Explain what changed and why
  4. Link Issues: Reference any related issues
  5. Keep PRs Focused: One feature/fix per PR when possible

Code Review

All submissions require review. We use GitHub pull requests for this purpose. The review process includes:

  • Code quality and style
  • Functionality testing
  • Documentation completeness
  • Performance considerations

Questions?

  • Open an issue for bugs or feature requests
  • Check existing issues and PRs first
  • Be respectful and constructive in discussions

Thank you for contributing to SyncVault! 🚀