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

   git clone https://github.com/YOUR_USERNAME/colorspaces.git
   cd colorspaces
   

2. Set up environment

   make setup
   

3. Make your changes

   • Edit app.py for functionality
   • Update README.md for documentation
   • Add images to images/ folder

4. Test locally

   make test
   make run
   

5. Commit and push

   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:

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:

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! 🎉