platform/doc/CONTRIBUTING.md

# Contributing to Framework Documentation

## Overview

This guide explains how to contribute to our framework documentation. We maintain comprehensive documentation covering package specifications, gap analyses, integration guides, and architectural documentation.

## Documentation Structure

### Core Documentation
1. [Getting Started Guide](getting_started.md) - Framework introduction and setup
2. [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md) - Implementation timeline
3. [Foundation Integration Guide](foundation_integration_guide.md) - Integration patterns
4. [Testing Guide](testing_guide.md) - Testing approaches
5. [Package Integration Map](package_integration_map.md) - Package relationships

### Core Architecture
1. [Core Architecture](core_architecture.md) - System design and patterns
2. [Core Package Specification](core_package_specification.md) - Core implementation

### Package Documentation
Each package has:
1. Package Specification - Implementation details
2. Gap Analysis - Laravel compatibility gaps
3. Integration Guide - Package integration patterns
4. Development Guidelines - Implementation standards

## Contribution Guidelines

### 1. Documentation Standards

#### File Naming
- Use lowercase with underscores
- End with .md extension
- Be descriptive and specific
- Examples:
  * package_specification.md
  * gap_analysis.md
  * integration_guide.md

#### File Structure
- Start with # Title
- Include Overview section
- Add Related Documentation links
- Use clear section headers
- Include code examples
- End with development guidelines

#### Content Requirements
- No placeholders or truncation
- Complete code examples
- Clear cross-references
- Proper markdown formatting
- Comprehensive coverage

### 2. Writing Style

#### Technical Writing
- Be clear and concise
- Use active voice
- Write in present tense
- Focus on technical accuracy
- Include practical examples

#### Code Examples
```dart
// Include complete, working examples
class Example {
  final String name;
  
  Example(this.name);
  
  void demonstrate() {
    print('Demonstrating: $name');
  }
}

// Show usage
var example = Example('feature');
example.demonstrate();
```

#### Cross-References
- Use relative links
- Link to related docs
- Reference specific sections
- Example:
  ```markdown
  See [Container Integration](container_package_specification.md#integration) for details.
  ```

### 3. Documentation Types

#### Package Specification
- Implementation details
- API documentation
- Integration examples
- Testing guidelines
- Development workflow

#### Gap Analysis
- Current implementation
- Laravel features
- Missing functionality
- Implementation plan
- Priority order

#### Integration Guide
- Integration points
- Package dependencies
- Code examples
- Best practices
- Common patterns

### 4. Review Process

#### Before Submitting
1. Check content completeness
2. Verify code examples
3. Test all links
4. Run markdown linter
5. Review formatting

#### Pull Request
1. Clear description
2. Reference related issues
3. List documentation changes
4. Include review checklist
5. Add relevant labels

#### Review Checklist
- [ ] No placeholders or truncation
- [ ] Complete code examples
- [ ] Working cross-references
- [ ] Proper formatting
- [ ] Technical accuracy

### 5. Development Workflow

#### Creating Documentation
1. Create feature branch
2. Write documentation
3. Add code examples
4. Include cross-references
5. Submit pull request

#### Updating Documentation
1. Review existing content
2. Make necessary changes
3. Update related docs
4. Verify all links
5. Submit pull request

#### Review Process
1. Technical review
2. Style review
3. Code example review
4. Cross-reference check
5. Final approval

## Style Guide

### 1. Markdown

#### Headers
```markdown
# Main Title
## Section Title
### Subsection Title
#### Minor Section
```

#### Lists
```markdown
1. Ordered Item
2. Ordered Item
   - Unordered Sub-item
   - Unordered Sub-item

- Unordered Item
- Unordered Item
  1. Ordered Sub-item
  2. Ordered Sub-item
```

#### Code Blocks
```markdown
/// Code with syntax highlighting
```dart
class Example {
  void method() {
    // Implementation
  }
}
```

/// Inline code
Use `var` for variable declaration.
```

#### Links
```markdown
[Link Text](relative/path/to/file.md)
[Link Text](relative/path/to/file.md#section)
```

### 2. Content Organization

#### Package Documentation
1. Overview
2. Core Features
3. Integration Examples
4. Testing
5. Development Guidelines

#### Gap Analysis
1. Overview
2. Missing Features
3. Implementation Gaps
4. Priority Order
5. Next Steps

#### Integration Guide
1. Overview
2. Integration Points
3. Code Examples
4. Best Practices
5. Development Guidelines

### 3. Code Examples

#### Complete Examples
```dart
// Include all necessary imports
import 'package:framework/core.dart';

// Show complete implementation
class ServiceProvider {
  final Container container;
  
  ServiceProvider(this.container);
  
  void register() {
    container.singleton<Service>((c) => 
      ServiceImplementation()
    );
  }
}

// Demonstrate usage
void main() {
  var container = Container();
  var provider = ServiceProvider(container);
  provider.register();
}
```

#### Integration Examples
```dart
// Show real integration scenarios
class UserService {
  final EventDispatcher events;
  final Database db;
  
  UserService(this.events, this.db);
  
  Future<void> createUser(User user) async {
    await events.dispatch(UserCreating(user));
    await db.users.insert(user);
    await events.dispatch(UserCreated(user));
  }
}
```

## Questions?

For questions or clarification:
1. Review existing documentation
2. Check style guide
3. Ask in pull request
4. Update guidelines as needed