Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
274 lines (202 loc) · 6.87 KB

CONTRIBUTING.md

File metadata and controls

274 lines (202 loc) · 6.87 KB

Contributing to Understand Anything

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

🌟 Ways to Contribute

  • Bug Reports: Found a bug? Open an issue with detailed reproduction steps
  • Feature Requests: Have an idea? Share it in the issues section
  • Documentation: Improve or translate documentation
  • Code: Fix bugs, add features, or improve performance
  • Testing: Write tests to improve code coverage

🚀 Getting Started

Prerequisites

  • Node.js >= 22 (developed on v24)
  • pnpm >= 10 (pinned via packageManager field in root package.json)
  • Git for version control

Setup

  1. Fork and Clone

    git clone https://github.com/YOUR_USERNAME/Understand-Anything.git
cd Understand-Anything

  2. Install Dependencies

    pnpm install

  3. Build Core Package

    pnpm --filter @understand-anything/core build

  4. Run Tests

    pnpm --filter @understand-anything/core test
pnpm --filter @understand-anything/skill test

  5. Start Dashboard (Optional)

    pnpm dev:dashboard

📝 Development Workflow

1. Create a Branch

Create a descriptive branch name:

git checkout -b feat/my-feature        # For new features
git checkout -b fix/bug-description    # For bug fixes
git checkout -b docs/update-readme     # For documentation

2. Make Changes

  • Write clean, readable code
  • Follow existing code style and conventions
  • Add tests for new functionality
  • Update documentation as needed

3. Test Your Changes

# Run all tests
pnpm --filter @understand-anything/core test
pnpm --filter @understand-anything/skill test

# Run linter
pnpm lint

# Build packages
pnpm build

4. Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "feat: add keyboard shortcuts to dashboard"

Commit Message Convention:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes (formatting, etc.)
  • refactor: - Code refactoring
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

5. Push and Create Pull Request

git push origin your-branch-name

Then open a Pull Request on GitHub with:

  • Clear title describing the change
  • Detailed description of what changed and why
  • Link to related issues (if any)
  • Screenshots (for UI changes)

🧪 Testing Guidelines

Writing Tests

  • Use Vitest for testing
  • Place tests in __tests__ directories or *.test.ts files
  • Aim for high test coverage for new features
  • Test edge cases and error conditions

Example test structure:

import { describe, it, expect } from 'vitest';

describe('MyFeature', () => {
  it('should do something', () => {
    // Arrange
    const input = 'test';

    // Act
    const result = myFunction(input);

    // Assert
    expect(result).toBe('expected');
  });
});

Running Tests

# Run all tests
pnpm test

# Run tests for specific package
pnpm --filter @understand-anything/core test

# Run tests in watch mode
pnpm --filter @understand-anything/core test --watch

📚 Code Style Guidelines

TypeScript

  • Use TypeScript strict mode
  • Define explicit types for function parameters and return values
  • Avoid any type - use unknown if type is truly unknown
  • Use interfaces for object shapes
  • Use type aliases for unions and complex types

Formatting

  • The project uses ESLint for code quality
  • Consistent indentation (2 spaces)
  • Use meaningful variable and function names
  • Keep functions small and focused

React/Dashboard

  • Use functional components with hooks
  • Keep components focused and single-purpose
  • Use Zustand for state management
  • Follow the existing component structure

Tech Stack

TypeScript, pnpm workspaces, React 18, Vite, TailwindCSS v4, React Flow, Zustand, web-tree-sitter, Fuse.js, Zod, Dagre

File Organization

understand-anything-plugin/
├── packages/
│   ├── core/              # Core analysis engine
│   │   ├── src/
│   │   └── package.json
│   └── dashboard/         # React dashboard
│       ├── src/
│       │   ├── components/
│       │   ├── utils/
│       │   └── store.ts
│       └── package.json
├── src/                   # Plugin skills implementation
├── agents/                # AI agent prompts
└── skills/                # Skill definitions

🌍 Translation Guidelines

Adding a New Language

  1. Create README.{language-code}.md (e.g., README.fr-FR.md)
  2. Translate all sections while maintaining formatting
  3. Update main README.md to include language link
  4. Keep technical terms in English where appropriate
  5. Ensure all links still work

Example:

<a href="README.md">English</a> | <a href="README.fr-FR.md">Français</a>

🐛 Bug Reports

When reporting bugs, include:

  • Description: Clear description of the issue
  • Steps to Reproduce: Detailed steps to reproduce the bug
  • Expected Behavior: What you expected to happen
  • Actual Behavior: What actually happened
  • Environment: OS, Node version, pnpm version
  • Screenshots: If applicable
  • Error Messages: Full error output

💡 Feature Requests

When requesting features:

  • Use Case: Describe the problem you're trying to solve
  • Proposed Solution: How you envision the feature working
  • Alternatives: Other solutions you've considered
  • Additional Context: Any other relevant information

📋 Pull Request Checklist

Before submitting a PR, ensure:

  • Code follows the project's style guidelines
  • All tests pass (pnpm test)
  • New code has test coverage
  • Documentation is updated (if needed)
  • Commit messages follow convention
  • PR description clearly explains changes
  • No console.log or debug code left behind
  • Branch is up to date with main

🤝 Code Review Process

  1. Automated Checks: CI runs tests and linting
  2. Maintainer Review: Project maintainers review the code
  3. Feedback: Address any requested changes
  4. Approval: Once approved, PR will be merged
  5. Cleanup: Delete your branch after merge

📞 Getting Help

  • Issues: For bugs and feature requests
  • Discussions: For questions and general discussion
  • Documentation: Check existing docs first

📄 License

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

🙏 Recognition

Contributors will be recognized in:

  • GitHub contributors list
  • Release notes (for significant contributions)
  • Special mentions for exceptional contributions

Thank you for contributing to Understand Anything! Your contributions help make code understanding accessible to everyone. 🚀