Hugging Face's logo

Spaces:
Kraft102
/
widgettdc-api
Paused

App Files Community
widgettdc-api / CONTRIBUTING.md
Kraft102's picture
Kraft102
fix: sql.js Docker/Alpine compatibility layer for PatternMemory and FailureMemory
5a81b95
preview code
|
raw
history blame contribute delete
7.99 kB

Contributing to WidgetBoard

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

Code of Conduct

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

Code Style Guidelines

EMOJIS ARE STRICTLY FORBIDDEN in all code, comments, documentation, and commit messages. Never use emojis anywhere in the codebase.

Getting Started

Prerequisites

  • Node.js 18+ or 20+
  • npm 9+
  • Git
  • Familiarity with React, TypeScript, and modern web development

Setup Development Environment

  1. Fork the repository on GitHub
  2. Clone your fork locally:
    git clone https://github.com/YOUR_USERNAME/WidgeTDC.git
cd WidgeTDC
  3. Add upstream remote:
    git remote add upstream https://github.com/Clauskraft/WidgeTDC.git
  4. Install dependencies:
    npm install --legacy-peer-deps
  5. Copy environment template:
    cp .env.example .env.local
  6. Start development server:
    npm run dev

Development Workflow

Branch Naming Convention

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring
  • test/description - Test additions or modifications
  • security/description - Security fixes

Making Changes

  1. Create a new branch:

    git checkout -b feature/your-feature-name

  2. Make your changes following our coding standards

  3. Write or update tests:

    npm test

  4. Run linter:

    npm run lint

  5. Format your code:

    npm run format

  6. Commit your changes:

    git commit -m "feat: add amazing feature"

Commit Message Convention

We follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • test: Test additions or modifications
  • chore: Build process or tooling changes
  • security: Security improvements

Examples:

feat(widgets): add email RAG widget
fix(security): prevent XSS in input fields
docs(readme): update installation instructions
test(utils): add security utility tests

Coding Standards

TypeScript

  • Use TypeScript for all new code
  • Define types for all function parameters and return values
  • Avoid any type unless absolutely necessary
  • Use interfaces for object shapes
  • Use enums for fixed sets of values

React

  • Use functional components with hooks
  • Keep components small and focused (< 300 lines)
  • Extract complex logic into custom hooks
  • Use memo/useMemo/useCallback for performance optimization
  • Implement error boundaries for widget isolation

Security

  • Sanitize all user input
  • Validate all external data
  • Use parameterized queries
  • Implement rate limiting
  • Follow OWASP guidelines
  • Never commit secrets or API keys

Testing

  • Write tests for all new features
  • Maintain minimum 70% code coverage
  • Test both happy paths and error cases
  • Use descriptive test names
  • Mock external dependencies

Code Style

  • Use Prettier for formatting
  • Follow ESLint rules
  • Use meaningful variable names
  • Add comments for complex logic
  • Keep functions small (< 50 lines)
  • Maximum line length: 100 characters

Testing

Running Tests 

# Run all tests
npm test

# Run specific test file
npm test -- security.test.ts

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test

Writing Tests 

import { describe, it, expect } from 'vitest';
import { sanitizeInput } from './security';

describe('sanitizeInput', () => {
  it('should remove XSS attempts', () => {
    const input = '<script>alert("xss")</script>';
    const result = sanitizeInput(input);
    expect(result).not.toContain('<script>');
  });
});

Pull Request Process

Before Submitting

  • Tests pass: npm test
  • Linter passes: npm run lint
  • Code formatted: npm run format
  • Build succeeds: npm run build
  • Documentation updated (if needed)
  • Changelog updated (for significant changes)

Submitting PR

  1. Push your branch to your fork:

    git push origin feature/your-feature-name

  2. Open a Pull Request on GitHub

  3. Fill out the PR template completely

  4. Link related issues

  5. Request review from maintainers

PR Template 

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests pass locally

Review Process

  • At least one approval required
  • All checks must pass
  • No unresolved conversations
  • Branch up to date with main
  • Squash and merge preferred

Documentation

Code Documentation

  • Add JSDoc comments for functions:
    /**
 * Sanitize user input to prevent XSS attacks
 * @param input - Raw user input string
 * @returns Sanitized string safe for display
 */
export function sanitizeInput(input: string): string {
  // Implementation
}

Architecture Decisions

Document significant architectural decisions in docs/ADR/:

# ADR-001: Use Circuit Breaker Pattern

## Status
Accepted

## Context
Need fault tolerance for external service calls

## Decision
Implement circuit breaker pattern in MCP client

## Consequences
- Improved resilience
- Faster failure detection
- Additional complexity

Security Guidelines

Security-First Mindset

  • Assume all input is malicious
  • Validate on server and client
  • Use allowlists over denylists
  • Fail securely
  • Log security events

Common Vulnerabilities to Avoid

  1. XSS (Cross-Site Scripting)

    • Sanitize all user input
    • Use Content Security Policy
    • Escape HTML entities

  2. SQL Injection

    • Use parameterized queries
    • Validate input types
    • Implement least privilege

  3. CSRF (Cross-Site Request Forgery)

    • Use CSRF tokens
    • Validate origin headers
    • SameSite cookies

  4. Authentication Issues

    • Use strong passwords
    • Implement MFA
    • Secure session management

Reporting Security Vulnerabilities

DO NOT open public issues for security vulnerabilities.

Email: security@widgetboard.example.com

Include:

  • Description of vulnerability
  • Steps to reproduce
  • Potential impact
  • Suggested fix (optional)

Performance Guidelines

Optimization Techniques

  • Lazy load components
  • Implement code splitting
  • Use React.memo for expensive components
  • Debounce user input
  • Throttle scroll/resize handlers
  • Optimize images and assets

Performance Testing 

import { logger } from './utils/logger';

const endTimer = logger.startTimer('Operation Name');
// ... your code ...
endTimer(); // Logs: Performance: Operation Name { duration: "12.34ms" }

Getting Help

Resources

Communication Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: Questions and general discussion
  • Email: dev@widgetboard.example.com

Recognition

Contributors will be recognized in:

  • README.md acknowledgments section
  • Release notes
  • GitHub contributors page

Thank you for contributing to WidgetBoard!