Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
246 lines (196 loc) · 6.77 KB

CONTRIBUTING.md

File metadata and controls

246 lines (196 loc) · 6.77 KB

Contributing to LLM Evals for Domain Experts

Thank you for your interest in contributing to LLM Evals for Domain Experts! This project aims to provide domain experts with a simple, secure, and efficient tool for evaluating LLM outputs.

🎯 Project Philosophy

This project is built with these core principles:

  • Simplicity: Single HTML file with no dependencies
  • Privacy: Complete local operation with no data transmission
  • Accessibility: Works for domain experts without technical background
  • Security: Air-gapped operation for sensitive data
  • Professionalism: Enterprise-grade UX and features

🚀 Ways to Contribute

1. Internationalization

Help make the tool available in more languages:

  • Add new language translations to the i18n object
  • Test existing translations for accuracy
  • Improve cultural adaptation of UI elements

2. Label Categories

Enhance evaluation options:

  • Suggest domain-specific error labels
  • Propose new quality assessment categories
  • Improve label descriptions and tooltips

3. Export Formats

Expand export capabilities:

  • Add support for new file formats
  • Improve metadata inclusion options
  • Enhance filename generation logic

4. User Experience

Improve the interface:

  • Enhance accessibility features
  • Improve responsive design
  • Add new keyboard shortcuts
  • Optimize performance for large datasets

5. Documentation

Help others use the tool:

  • Improve README sections
  • Add usage examples
  • Create video tutorials
  • Write domain-specific guides

🛠️ Development Guidelines

File Structure

LLM-Evals-Domain-Expert/
├── llm-evals-standalone.html    # Main application file
├── README.md                    # Project documentation
├── LICENSE                      # MIT license
├── CONTRIBUTING.md             # This file
└── .gitignore                  # Git ignore rules

Code Organization

The main application is contained in llm-evals-standalone.html with:

  • HTML Structure: Semantic markup for accessibility
  • CSS Styles: Modern, responsive design system
  • JavaScript Logic: Modular class-based architecture
  • Internationalization: Centralized translation system

Making Changes

  1. Fork the Repository

    git clone https://github.com/your-username/Evals-Domain-Expert.git
cd Evals-Domain-Expert

  2. Create a Feature Branch

    git checkout -b feature/your-feature-name

  3. Make Your Changes

    • Edit llm-evals-standalone.html
    • Test thoroughly across browsers
    • Ensure no external dependencies are added

  4. Test Your Changes

    • Test in Chrome, Firefox, Safari, and Edge
    • Test on mobile devices
    • Test with various CSV file sizes
    • Test all language translations
    • Verify offline functionality

  5. Commit Your Changes

    git add .
git commit -m "Add: descriptive commit message"

  6. Push and Create Pull Request

    git push origin feature/your-feature-name

🧪 Testing Guidelines

Browser Testing

  • Chrome/Chromium: Primary development browser
  • Firefox: Ensure compatibility with standard scrollbars
  • Safari: Test on macOS and iOS
  • Edge: Verify enterprise compatibility

Functionality Testing

  • File Import: Test various CSV formats and sizes
  • Evaluation Flow: Test all approval/rejection workflows
  • Export Functions: Verify all export formats and options
  • Keyboard Shortcuts: Test all hotkey combinations
  • Responsive Design: Test on various screen sizes

Data Testing

  • Small Files: < 10 items
  • Medium Files: 50-100 items
  • Large Files: 200-500 items
  • Edge Cases: Empty files, malformed CSV, special characters

📝 Pull Request Guidelines

Before Submitting

  • Feature works in all major browsers
  • Code follows existing patterns and style
  • No external dependencies added
  • All languages updated if UI text changed
  • Responsive design maintained
  • Accessibility not compromised

PR Description Template

## Description
Brief description of changes made.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Internationalization
- [ ] Performance improvement

## Testing
- [ ] Tested in Chrome
- [ ] Tested in Firefox
- [ ] Tested in Safari/Edge
- [ ] Tested on mobile
- [ ] Tested with large datasets

## Screenshots (if applicable)
Add screenshots for UI changes.

🏷️ Adding New Labels

Error Labels

Add to the errorLabels section of each language:

newErrorType: "Description of Error",

Quality Labels

Add to the qualityLabels section:

newQualityType: "Description of Quality",

Validation

  • Keep labels concise (< 25 characters)
  • Use consistent naming conventions
  • Ensure translations are culturally appropriate
  • Test label UI rendering

🌐 Internationalization Guidelines

Adding a New Language

  1. Add language code to i18n object
  2. Copy entire English translation structure
  3. Translate all strings maintaining:
    • HTML structure (for rich text)
    • Placeholder variables (e.g., ${count})
    • Keyboard shortcut indicators

Translation Quality

  • Use domain-appropriate terminology
  • Maintain professional tone
  • Consider cultural context
  • Test with native speakers when possible

🐛 Reporting Issues

Bug Reports

Please include:

  • Browser and version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshot if applicable
  • Sample CSV file (if relevant)

Feature Requests

Please describe:

  • Use case and motivation
  • Proposed solution
  • Alternative solutions considered
  • Impact on existing functionality

💡 Design Principles

User Experience

  • Domain Expert First: Optimize for professional evaluators
  • Keyboard Efficiency: Support mouse-free operation
  • Visual Clarity: Clear status indicators and progress tracking
  • Error Prevention: Validate inputs and provide clear feedback

Technical Excellence

  • Performance: Smooth operation with large datasets
  • Reliability: Robust error handling and data persistence
  • Security: No external communications or dependencies
  • Maintainability: Clean, well-documented code

🤝 Community

Communication

  • Use GitHub Issues for bugs and feature requests
  • Use GitHub Discussions for questions and ideas
  • Be respectful and constructive in all interactions
  • Help others learn and contribute

Recognition

Contributors will be recognized in:

  • README acknowledgments
  • Release notes
  • Project documentation

📜 License

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

Thank you for helping make LLM evaluation more accessible and secure for domain experts worldwide! 🌟