Understand-Anything/CONTRIBUTING.md

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

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. 🚀