Contributing

Thank you for your interest in contributing to the ASL Methods Section Generator! This document provides guidelines and information for contributors.

How to Contribute

We welcome contributions from the community in various forms:

Bug Reports: Help us identify and fix issues
Feature Requests: Suggest new functionality
Code Contributions: Submit pull requests with improvements
Documentation: Improve or expand our documentation
Testing: Help test new features and report issues
Community Support: Help other users in discussions

Before You Start

Prerequisites

Familiarity with Python, JavaScript/TypeScript, and web development
Understanding of ASL (Arterial Spin Labeling) concepts
Knowledge of medical imaging standards (BIDS, DICOM)
Git and GitHub workflow experience

Development Environment Setup

Follow the Getting Started Guide to set up your development environment
Ensure all tests pass before making changes
Familiarize yourself with the project structure and architecture

Reporting Bugs

Before Reporting

Check if the issue has already been reported
Try to reproduce the issue with the latest version
Check the troubleshooting guide for common solutions

Bug Report Template

**Bug Description**
A clear and concise description of the bug.

**Steps to Reproduce**
1. Go to '...'
2. Click on '...'
3. Upload '...'
4. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**
- OS: [e.g., Windows 10, macOS 12.0, Ubuntu 20.04]
- Browser: [e.g., Chrome 96, Firefox 95]
- Python Version: [e.g., 3.11.0]
- Node.js Version: [e.g., 18.0.0]

**Additional Context**
- Screenshots if applicable
- Error messages or logs
- Sample data that reproduces the issue

Requesting Features

Feature Request Template

**Feature Description**
A clear and concise description of the feature you'd like to see.

**Use Case**
Describe the problem this feature would solve or the workflow it would improve.

**Proposed Solution**
If you have ideas for implementation, describe them here.

**Alternative Solutions**
Any alternative solutions or features you've considered.

**Additional Context**
- Screenshots or mockups if applicable
- Related issues or discussions
- Impact on existing functionality

Code Contributions

Development Workflow

1. Fork and Clone

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/your-username/ASL-Methods-Generator.git
cd ASL-Methods-Generator

# Add the original repository as upstream
git remote add upstream https://github.com/original-repo/ASL-Methods-Generator.git

2. Create a Feature Branch

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Or for bug fixes
git checkout -b fix/your-bug-description

3. Make Your Changes

Follow the coding standards outlined below
Write tests for new functionality
Update documentation as needed
Keep commits small and focused

4. Test Your Changes

# Run all tests
docker-compose up --build
# Or run tests individually
cd apps/backend && python -m pytest
cd apps/frontend && yarn test
cd package && python -m pytest

5. Submit a Pull Request

Push your branch to your fork
Create a pull request with a clear description
Reference any related issues
Request reviews from maintainers

Coding Standards

Python (Backend & Package)

Style Guide: Follow PEP 8
Formatting: Use Black for code formatting
Import Sorting: Use isort for import organization
Type Hints: Use type hints for all functions
Documentation: Use Google-style docstrings

def process_asl_data(data: Dict[str, Any]) -> Dict[str, Any]:
    """
    Process ASL data and generate validation report.
    
    Args:
        data: Dictionary containing ASL data and file paths
        
    Returns:
        Dictionary containing processing results and reports
        
    Raises:
        ValueError: If required data is missing
        ProcessingError: If data processing fails
    """
    # Implementation here
    pass

TypeScript/JavaScript (Frontend)

Style Guide: Follow ESLint configuration
Formatting: Use Prettier
Type Safety: Use TypeScript for all new code
Components: Use functional components with hooks
Naming: Use camelCase for variables, PascalCase for components

interface ASLData {
  modality: string;
  files: File[];
  niftiFile: File;
}

const ASLProcessor: React.FC<{ data: ASLData }> = ({ data }) => {
  // Component implementation
};

General Guidelines

Commit Messages: Use conventional commit format

feat: add new ASL validation rule
fix: resolve file upload issue
docs: update API documentation
test: add unit tests for validator

File Naming: Use descriptive, consistent names
Error Handling: Provide meaningful error messages
Logging: Use appropriate log levels and messages

Testing Guidelines

Backend Tests

# tests/test_asl_processor.py
import pytest
from pyaslreport.modalities.asl.processor import ASLProcessor

class TestASLProcessor:
    def test_valid_asl_data(self):
        """Test processing of valid ASL data."""
        data = {
            "modality": "asl",
            "files": ["test_asl.json"],
            "nifti_file": "test_asl.nii.gz"
        }
        processor = ASLProcessor(data)
        result = processor.process()
        
        assert result is not None
        assert "report" in result
        assert "parameters" in result

Frontend Tests

// __tests__/components/UploadButton.test.tsx
import { render, fireEvent } from '@testing-library/react';
import UploadButton from '../UploadButton';

describe('UploadButton', () => {
  it('should handle file upload correctly', () => {
    const mockOnUpload = jest.fn();
    const { getByLabelText } = render(
      <UploadButton onUpload={mockOnUpload} />
    );
    
    const file = new File(['test'], 'test.json', { type: 'application/json' });
    const input = getByLabelText(/upload/i);
    
    fireEvent.change(input, { target: { files: [file] } });
    
    expect(mockOnUpload).toHaveBeenCalledWith([file]);
  });
});

Documentation Standards

Code Documentation

Document all public APIs and functions
Include usage examples
Explain complex algorithms
Update documentation when changing functionality

User Documentation

Write clear, concise instructions
Include screenshots for UI changes
Provide troubleshooting information
Keep documentation up to date

Review Process

Pull Request Review Checklist

Code follows style guidelines
Tests are included and passing
Documentation is updated
No breaking changes (or properly documented)
Error handling is appropriate
Performance considerations addressed
Security implications considered

Review Guidelines

Be constructive and respectful
Focus on the code, not the person
Provide specific, actionable feedback
Suggest improvements when possible
Approve when satisfied with changes

Release Process

Versioning

We follow Semantic Versioning:

Major: Breaking changes
Minor: New features (backward compatible)
Patch: Bug fixes (backward compatible)

Getting Help

Communication Channels

GitHub Issues: For bug reports and feature requests
GitHub Discussions: For questions and community support
Email: For sensitive or private matters

Contribution Types

Code: Direct code contributions
Documentation: Documentation improvements
Testing: Bug reports and testing
Community: Helping other users
Design: UI/UX improvements

Code of Conduct

Our Standards

Be respectful and inclusive
Use welcoming and inclusive language
Be collaborative and constructive
Focus on what is best for the community
Show empathy towards other community members

Enforcement

Unacceptable behavior will not be tolerated
Maintainers will address violations
Consequences may include temporary or permanent bans

License

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

Ready to Contribute? Start by checking out the Getting Started Guide and then look for issues labeled "good first issue" or "help wanted" in the GitHub repository.

Introduction

User Guide

Development

Next Steps