[api-review] Configuration File Enhancement Proposal

A more long-term backlog proposal, created on the side. 
Might get relevant, as soon as the default parameter and the "dynamic discovery" of the tooling repository is no longer sufficient and/or any of the proposed parameters below make sense.

----------------

## Overview

Enhance the CAMARA API Review workflow system to support repository-specific configuration files, enabling fine-grained control over validation behavior, tooling selection, and reporting preferences.

## Problem Statement

Currently, the API review workflow uses hardcoded defaults with limited customization options. Users need more control over:
- Which tooling repository to use (especially for forks and testing)
- Validation rule customization and exceptions
- Reporting format and detail level
- Integration with external tools
- Repository-specific validation requirements

## Proposed Solution

### Configuration File Location
- **Path**: `.github/camara-config.yml`
- **Rationale**: 
  - Not included in release packages
  - Version-controlled alongside workflow files
  - Standard GitHub configuration location
  - Easy to find and maintain

### Configuration Schema

```yaml
# .github/camara-config.yml

# Tooling Repository Configuration
tooling:
  repository: "camaraproject/tooling"    # Which tooling repo to use
  version: "main"                        # Branch/tag reference
  fallback: "camaraproject/tooling"      # Fallback if primary unavailable

# Validation Configuration
validation:
  commonalities_version: "0.6"          # CAMARA Commonalities version
  review_types: 
    - "release-candidate"                # Allowed review types
    - "wip"
  
  # Exception Handling
  exceptions:
    skip_rules: []                       # Validation rules to skip
    allow_warnings: true                 # Allow warnings without failure
    custom_error_codes: []               # Additional allowed error codes
    max_critical_issues: 0               # Max critical issues before failure
  
  # Custom Validation
  custom_rules:
    company_standards: false             # Enable company-specific checks
    additional_rule_files: []            # Custom rule files to load

# Reporting Configuration  
reporting:
  format: "detailed"                     # "detailed" | "summary" | "minimal"
  include_passed_checks: false          # Show successful validations
  max_issues_display: 25                # Limit issues in comments
  group_by_severity: true               # Group issues by severity
  
  # Artifact Configuration
  artifacts:
    retention_days: 30                   # How long to keep reports
    include_raw_data: false              # Include raw validation data
    
# Notification Settings
notifications:
  on_success: "comment"                  # "comment" | "none"
  on_failure: "comment"                  # "comment" | "none"
  mention_on_failure: []                 # GitHub users to mention
  
  # External Integrations
  integrations:
    slack_webhook: ""                    # Slack notifications (optional)
    teams_webhook: ""                    # Teams notifications (optional)

# Repository-Specific Settings
repository:
  api_directories: 
    - "code/API_definitions"             # Where to find API files
  exclude_files: []                      # Files to skip validation
  required_files: 
    - "CHANGELOG.md"                     # Files that must exist
  
  # Special Handling
  legacy_mode: false                     # Use legacy validation rules
  experimental_features: false          # Enable experimental validations
```

## Key Benefits

### 1. **Flexibility**
- Repository-specific customization
- Support for different tooling versions
- Granular control over validation behavior

### 2. **Testing & Development**
- Fork-friendly configuration
- Easy testing of new tooling versions
- Custom validation rules for specific needs

### 3. **Enterprise Integration**
- Company-specific validation rules
- External tool integrations
- Custom reporting formats

### 4. **Maintainability**
- Version-controlled configuration
- Self-documenting settings
- Clear upgrade path for new features

## Implementation Details

### Phase 1: Core Configuration Support
**Duration**: 1 week
- Basic config file parsing
- Tooling repository selection
- Validation settings (commonalities_version, review_types)
- Basic reporting options

### Phase 2: Advanced Validation Control
**Duration**: 1 week  
- Exception handling (skip_rules, custom_error_codes)
- Custom validation rules
- Enhanced reporting options
- Artifact configuration

### Phase 3: External Integrations
**Duration**: 1 week
- Slack/Teams notifications
- Custom notification templates
- Repository-specific settings
- Legacy mode support

## Technical Implementation

### Configuration Loading Logic
```yaml
# In api-review-trigger.yml
- name: Load Configuration
  id: config
  run: |
    if [ -f ".github/camara-config.yml" ]; then
      echo "✅ Found configuration file"
      # Parse YAML and extract values
      TOOLING_REPO=$(yq '.tooling.repository // "camaraproject/tooling"' .github/camara-config.yml)
      TOOLING_VERSION=$(yq '.tooling.version // "main"' .github/camara-config.yml)
      COMMONALITIES_VERSION=$(yq '.validation.commonalities_version // "0.6"' .github/camara-config.yml)
      REPORTING_FORMAT=$(yq '.reporting.format // "detailed"' .github/camara-config.yml)
    else
      echo "ℹ️ No configuration file found, using defaults"
      TOOLING_REPO="camaraproject/tooling"
      TOOLING_VERSION="main"
      COMMONALITIES_VERSION="0.6"
      REPORTING_FORMAT="detailed"
    fi
    
    echo "tooling_repo=$TOOLING_REPO" >> $GITHUB_OUTPUT
    echo "tooling_version=$TOOLING_VERSION" >> $GITHUB_OUTPUT
    echo "commonalities_version=$COMMONALITIES_VERSION" >> $GITHUB_OUTPUT
    echo "reporting_format=$REPORTING_FORMAT" >> $GITHUB_OUTPUT
```

### Validation Configuration
```yaml
# Pass configuration to reusable workflow
call-review-workflow:
  uses: ${{ steps.config.outputs.tooling_repo }}/.github/workflows/api-review-reusable.yml@${{ steps.config.outputs.tooling_version }}
  with:
    commonalities_version: ${{ steps.config.outputs.commonalities_version }}
    reporting_format: ${{ steps.config.outputs.reporting_format }}
    # ... other configuration parameters
```

### Error Handling
```yaml
- name: Validate Configuration
  run: |
    if [ -f ".github/camara-config.yml" ]; then
      # Validate YAML syntax
      if ! yq eval '.tooling.repository' .github/camara-config.yml > /dev/null; then
        echo "❌ ERROR: Invalid configuration file syntax"
        exit 1
      fi
      
      # Validate required fields
      TOOLING_REPO=$(yq '.tooling.repository // ""' .github/camara-config.yml)
      if [ -z "$TOOLING_REPO" ]; then
        echo "❌ ERROR: tooling.repository is required"
        exit 1
      fi
    fi
```

## Migration Strategy

### Backward Compatibility
- **Graceful Fallback**: If no config file exists, use current defaults
- **Progressive Enhancement**: Add features incrementally
- **No Breaking Changes**: Existing workflows continue working

### Adoption Path
1. **Optional**: Config file is completely optional initially
2. **Documentation**: Provide examples and templates
3. **Gradual Rollout**: Start with power users and forks
4. **Eventually Standard**: Become recommended best practice

## Example Use Cases

### 1. Fork Testing
```yaml
# In myuser/QualityOnDemand/.github/camara-config.yml
tooling:
  repository: "myuser/tooling"
  version: "experimental-features"
  
validation:
  exceptions:
    allow_warnings: true
    skip_rules: ["strict-version-check"]
```

### 2. Enterprise Deployment
```yaml
# In company/internal-api/.github/camara-config.yml
tooling:
  repository: "company/camara-tooling"
  version: "v1.2.0"
  
validation:
  custom_rules:
    company_standards: true
    additional_rule_files: ["security-rules.yml"]
    
notifications:
  integrations:
    slack_webhook: "https://hooks.slack.com/..."
    mention_on_failure: ["@api-team"]
```

### 3. Development/Testing
```yaml
# In developer-fork/.github/camara-config.yml
tooling:
  repository: "camaraproject/tooling"
  version: "main"
  
validation:
  exceptions:
    max_critical_issues: 5
    allow_warnings: true
    
reporting:
  format: "summary"
  include_passed_checks: false
```

## Risks and Mitigation

### Risk 1: Configuration Complexity
- **Mitigation**: Provide clear documentation and examples
- **Mitigation**: Use sensible defaults for all options
- **Mitigation**: Validate configuration and provide helpful error messages

### Risk 2: Maintenance Overhead
- **Mitigation**: Keep configuration schema stable
- **Mitigation**: Provide migration guides for schema changes
- **Mitigation**: Use semantic versioning for configuration format

### Risk 3: Security Considerations
- **Mitigation**: Validate all configuration values
- **Mitigation**: Sanitize external URLs and webhooks
- **Mitigation**: Limit scope of custom rules and integrations

## Success Metrics

### Adoption Metrics
- Number of repositories using configuration files
- Percentage of workflows using custom settings
- Feedback from users on flexibility and ease of use

### Quality Metrics
- Reduction in workflow configuration issues
- Increased usage of advanced features
- Improved user satisfaction with customization options

## Future Enhancements

### Advanced Features
- **Configuration Validation**: JSON Schema validation for config files
- **Configuration UI**: GitHub App for easier configuration management
- **Template Library**: Pre-built configuration templates for common use cases
- **Configuration Inheritance**: Org-level default configurations

### Integration Opportunities
- **CAMARA Registry**: Integration with CAMARA API registry
- **Quality Gates**: Integration with quality gate systems
- **Metrics Collection**: Enhanced metrics and analytics

## Dependencies

### Technical Dependencies
- `yq` tool for YAML parsing in GitHub Actions
- Enhanced error handling in workflow files
- Documentation updates for configuration options

### Process Dependencies
- Agreement on configuration file schema
- Testing with multiple repository types
- User feedback and iteration cycles

## Conclusion

The configuration file enhancement will significantly improve the flexibility and usability of the CAMARA API Review workflow system. By providing repository-specific customization options, we enable better testing, enterprise integration, and user-specific requirements while maintaining backward compatibility.

This enhancement aligns with the goal of making the CAMARA tooling more modular and extensible, supporting the diverse needs of the CAMARA community while maintaining consistency and quality standards.

---

**Next Steps:**
1. Review and approve this proposal
2. Implement basic dynamic discovery (Option A) first
3. Plan implementation phases based on priority
4. Gather user feedback on desired configuration options
5. Create detailed implementation specifications

[api-review] Configuration File Enhancement Proposal #25

Description

Overview

Problem Statement

Proposed Solution

Configuration File Location

Configuration Schema

Key Benefits

1. Flexibility

2. Testing & Development

3. Enterprise Integration

4. Maintainability

Implementation Details

Phase 1: Core Configuration Support

Phase 2: Advanced Validation Control

Phase 3: External Integrations

Technical Implementation

Configuration Loading Logic

Validation Configuration

Error Handling

Migration Strategy

Backward Compatibility

Adoption Path

Example Use Cases

1. Fork Testing

2. Enterprise Deployment

3. Development/Testing

Risks and Mitigation

Risk 1: Configuration Complexity

Risk 2: Maintenance Overhead

Risk 3: Security Considerations

Success Metrics

Adoption Metrics

Quality Metrics

Future Enhancements

Advanced Features

Integration Opportunities

Dependencies

Technical Dependencies

Process Dependencies

Conclusion

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions