Contributing

Thank you for your interest in contributing to RunCache! 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. Please read it before contributing.

Getting Started

Prerequisites

Node.js (version 14 or higher)
npm or yarn
Git

Setting Up the Development Environment

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/run-cache.git
cd run-cache

Install dependencies:
```
npm install
```
Set up pre-commit hooks:
```
npm run prepare
```

Create a branch for your changes:

git checkout -b feature/your-feature-name

Development Workflow

Running Tests

We use Jest for testing. Run the full test suite:

npm test

Run tests in watch mode during development:

npm run test:watch

Run tests with coverage:

npm run test:coverage

Linting

We use ESLint and Prettier for code quality:

npm run lint        # Check for issues
npm run lint:fix    # Fix issues automatically
npm run format      # Format code with Prettier

Building the Library

Build the library:

npm run build

Running Examples

The project includes example applications in the examples directory. You can run them to test your changes:

# Run the browser example
cd examples/browser
npm install
npm start

# Run the Node.js example
cd examples/node
npm install
npm start

Making Changes

Coding Standards

Follow the existing code style
Write clean, readable, and maintainable code
Include comments where necessary
Update documentation for any changed functionality
Add tests for new features or bug fixes

Commit Guidelines

We follow Conventional Commits for commit messages:

type(scope): short description

longer description if needed

Types include:

feat: A new feature
fix: A bug fix
docs: Documentation changes
style: Changes that don't affect code functionality (formatting, etc.)
refactor: Code changes that neither fix bugs nor add features
perf: Performance improvements
test: Adding or updating tests
chore: Changes to build process, tooling, etc.

Examples:

feat(api): add support for custom serialization
fix(storage): resolve issue with localStorage persistence
docs(readme): update installation instructions

Pull Request Process

Before submitting a PR:
- Update your fork with the latest changes from the main repository
- Ensure all tests pass
- Make sure your code follows our coding standards
- Add/update tests for your changes
- Update documentation as needed
Submit your PR:
- Fill out the PR template
- Link any relevant issues
- Provide a clear description of the changes and their purpose
- Include screenshots or examples if applicable
Code Review Process:
- A maintainer will review your PR
- Address any feedback or changes requested
- Once approved, a maintainer will merge your PR

Dependency Management

Avoid adding new dependencies unless absolutely necessary
If you need to add a dependency, explain why in your PR description
Prefer smaller, focused packages over large frameworks

Types of Contributions

Bug Fixes

Bug fixes are always welcome! If you find a bug:

Check if it's already reported in the Issues tab
If not, create a new issue with steps to reproduce
If you want to fix it yourself, mention that in the issue and submit a PR

Features

For new features:

First open an issue describing the feature and its benefits
Wait for discussion and approval from maintainers
Once approved, implement the feature and submit a PR

Documentation

Documentation improvements are highly valued:

Fix typos or unclear explanations
Add examples or use cases
Update outdated information
Improve API documentation

Performance Improvements

Performance improvements should:

Include before/after benchmarks
Maintain compatibility with existing APIs
Not sacrifice code readability for minor optimizations

Testing Guidelines

Unit Tests

Each new feature should include unit tests
Bug fixes should include tests that reproduce the bug
Tests should be fast and deterministic
Try to achieve high test coverage for new code

Integration Tests

Integration tests should verify that components work together
Mock external dependencies when needed
Test both successful and error scenarios

Test Naming

Name tests clearly and descriptively:

describe('RunCache', () => {
  describe('get', () => {
    it('should return undefined for non-existent keys', () => {
      // Test implementation
    });
    
    it('should return the cached value for existing keys', () => {
      // Test implementation
    });
    
    it('should not return expired values', () => {
      // Test implementation
    });
  });
});

Documentation Guidelines

Code Documentation

Use JSDoc comments for functions, classes, and methods
Document parameters, return values, and thrown exceptions
Include examples for complex functionality

Example:

/**
 * Sets a value in the cache with the given options.
 * 
 * @param options - The options for setting the cache entry
 * @param options.key - Unique identifier for the cache entry
 * @param options.value - String value to cache (required if no sourceFn)
 * @param options.ttl - Time-to-live in milliseconds
 * @param options.autoRefetch - Automatically refetch on expiry
 * @param options.sourceFn - Function to generate cache value
 * @param options.tags - Array of tags for tag-based invalidation
 * @param options.dependencies - Array of cache keys this entry depends on
 * @returns A Promise that resolves when the operation completes
 * @throws Error if key is empty, or if neither value nor sourceFn is provided
 * 
 * @example
 * ```typescript
 * // Set a simple value
 * await RunCache.set({ key: 'user', value: JSON.stringify({ name: 'John' }) });
 * 
 * // Set with TTL and auto-refetch
 * await RunCache.set({
 *   key: 'weather',
 *   sourceFn: async () => JSON.stringify(await fetchWeather()),
 *   ttl: 300000,
 *   autoRefetch: true
 * });
 * ```
 */
async set(options: SetOptions): Promise<void> {
  // Implementation
}

README and Documentation

Update relevant documentation for new features
Ensure examples are accurate and working
Use clear, concise language
Include visuals where appropriate (diagrams, screenshots)

Release Process

Maintainers handle releases following this process:

Update version in package.json according to Semantic Versioning
Update the CHANGELOG.md file
Create a new release on GitHub with release notes
Publish to npm

Creating a Good Issue

When creating an issue:

Use a clear, descriptive title
Include your environment details (Node.js version, browser, etc.)
Provide steps to reproduce
Describe expected and actual behavior
Add screenshots or code examples if relevant
Use issue templates when available

Becoming a Maintainer

Active contributors may be invited to become maintainers. Maintainers:

Have write access to the repository
Review and merge PRs
Help with issue triage
Guide the project direction
Maintain code quality and test coverage

Questions?

If you have questions about contributing, please:

Start a discussion in the GitHub Discussions tab
Ask in the issues tab with the "question" label
Reach out to the maintainers

Thank you for contributing to RunCache!

PreviousFAQ NextLicense

Last updated 24 days ago