CONTRIBUTING.md

# 🤝 Contributing to Colorspace Explorer

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

## Ways to Contribute

### 1. Report Bugs 🐛
- Use the GitHub issue tracker
- Include steps to reproduce
- Provide screenshots if applicable
- Mention your OS and Python version

### 2. Suggest Features 💡
- Open an issue with the "enhancement" label
- Explain the educational value
- Provide examples or mockups if possible

### 3. Add New Colorspaces 🎨
Good candidates:
- XYZ (CIE 1931)
- LCH (Lightness, Chroma, Hue)
- LUV
- HSL (alternative to HSV)
- Oklab (modern perceptual space)

### 4. Improve Documentation 📚
- Fix typos or unclear explanations
- Add more educational content
- Improve examples
- Translate documentation

### 5. Add Test Images 🖼️
- Standard test images
- Colorblind test patterns
- Images that demonstrate specific concepts
- Diverse content (people, nature, graphics)

## Development Setup

1. **Fork and clone**
   ```bash
   git clone https://github.com/YOUR_USERNAME/colorspaces.git
   cd colorspaces
   ```

2. **Set up environment**
   ```bash
   make setup
   ```

3. **Make your changes**
   - Edit `app.py` for functionality
   - Update `README.md` for documentation
   - Add images to `images/` folder

4. **Test locally**
   ```bash
   make test
   make run
   ```

5. **Commit and push**
   ```bash
   git add .
   git commit -m "Description of changes"
   git push origin your-branch-name
   ```

6. **Create Pull Request**
   - Go to GitHub
   - Click "New Pull Request"
   - Describe your changes
   - Link any related issues

## Code Style Guidelines

### Python Code
- Follow PEP 8 style guide
- Use meaningful variable names
- Add docstrings to functions
- Keep functions focused and short
- Comment complex algorithms

### Streamlit UI
- Use clear, descriptive labels
- Include help text for sliders
- Provide informative captions
- Use emojis sparingly for visual interest
- Maintain consistent layout patterns

### Documentation
- Use clear, concise language
- Include code examples
- Add links to references
- Explain educational purpose
- Use proper Markdown formatting

## Adding a New Colorspace Tab

Here's a template for adding a new colorspace:

```python
def tab_new_colorspace():
    """Brief description of the colorspace."""
    st.header("🎨 Colorspace Name")
    
    st.markdown("""
    **Brief description** with key properties:
    
    - **Property 1**: Description
    - **Property 2**: Description
    - **Use cases**: When to use this space
    """)
    
    col1, col2 = st.columns([1, 2])
    
    with col1:
        st.subheader("Controls")
        
        # Add interactive controls
        param1 = st.slider("Parameter 1", min_val, max_val, default)
        param2 = st.slider("Parameter 2", min_val, max_val, default)
        
        # Show color swatch or visualization
        # ...
    
    with col2:
        st.subheader("Image Analysis")
        
        # Image selection and processing
        images = get_available_images()
        if images:
            selected_img = st.selectbox("Select image:", images)
            img = load_image(selected_img)
            
            if img is not None:
                # Process and display
                # ...
    
    st.markdown("---")
    st.markdown("""
    ### 💡 Key Insights
    
    - Point 1
    - Point 2
    - Applications
    """)
```

Then add it to the main tabs:

```python
tabs = st.tabs([..., "New Colorspace"])

with tabs[N]:
    tab_new_colorspace()
```

## Testing Guidelines

Before submitting:

1. **Functionality**
   - [ ] All sliders work correctly
   - [ ] Images load and display properly
   - [ ] Conversions are mathematically correct
   - [ ] No errors in console

2. **UI/UX**
   - [ ] Layout looks good on different screen sizes
   - [ ] Labels are clear and descriptive
   - [ ] Help text is informative
   - [ ] Before/after comparisons are intuitive

3. **Educational Value**
   - [ ] Explanations are clear and accurate
   - [ ] Key insights are provided
   - [ ] Examples are relevant
   - [ ] References are included

4. **Performance**
   - [ ] Images resize appropriately
   - [ ] No lag with sliders
   - [ ] Matplotlib figures are closed
   - [ ] Memory usage is reasonable

## Commit Message Guidelines

Use clear, descriptive commit messages:

- `feat: Add XYZ colorspace tab`
- `fix: Correct CMYK to RGB conversion formula`
- `docs: Update README with new features`
- `style: Improve layout of HSV tab`
- `refactor: Extract common image loading code`
- `test: Add test for LAB color difference`

## Questions?

- Open an issue for questions
- Tag maintainers for help
- Check existing issues first

## Code of Conduct

- Be respectful and inclusive
- Welcome newcomers
- Focus on constructive feedback
- Assume good intentions
- Keep discussions on-topic

## Recognition

Contributors will be acknowledged in:
- README.md
- Release notes
- Project documentation

Thank you for contributing! 🎉