agentic-data-stack-community/CONTRIBUTING.md

AI Agentic Data Stack Framework - Community Edition. Open source data engineering framework with 4 core agents, essential templates, and 3-dimensional quality validation.

# Contributing to AI Agentic Data Stack Framework - Community Edition

Thank you for your interest in contributing to the AI Agentic Data Stack Framework! This document provides guidelines for contributing to the Community Edition.

## 🌟 How to Contribute

We welcome contributions in many forms:
- **Code improvements** and new features
- **Documentation** enhancements and tutorials
- **Examples** and use case implementations
- **Bug reports** and issue identification
- **Template contributions** for common scenarios
- **Testing** and quality assurance

## 🚀 Getting Started

### 1. Fork and Clone
```bash
# Fork the repository on GitHub
git clone https://github.com/barnyp/agentic-data-stack-framework-community
cd agentic-data-stack-framework-community
```

### 2. Set Up Development Environment
```bash
# Install dependencies
npm install

# Install CLI globally for testing
npm link

# Validate setup
agentic-data validate
```

### 3. Create a Branch
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description
```

## 📋 Contribution Types

### 🤖 AI Agent Contributions

**Adding New Agent Capabilities**
- Enhance existing agent YAML files
- Add new capabilities to core agents
- Improve agent personas and instructions

**File Structure**:
```yaml
# agents/agent-name.yaml
agent_metadata:
  name: "Agent Name"
  role: "Primary Role"
  specialty: "Area of Expertise"

core_capabilities:
  - "Primary capability 1"
  - "Primary capability 2"

deliverables:
  - "Key deliverable 1"
  - "Key deliverable 2"
```

### 📋 Template Contributions

**Adding New Templates**
- Create templates for common use cases
- Improve existing template quality
- Add industry-specific solutions

**Template Guidelines**:
- Use YAML format with clear metadata
- Include comprehensive documentation
- Provide realistic examples
- Test with sample data

**File Structure**:
```yaml
# templates/category/template-name.yaml
template_metadata:
  name: "Template Name"
  description: "Clear description"
  category: "business-intelligence | data-contracts | implementation | project-setup"
  complexity: "beginner | intermediate | advanced"
  estimated_time: "2-4 hours"

use_cases:
  - "Use case 1"
  - "Use case 2"

deliverables:
  - "Output 1"
  - "Output 2"
```

### 📚 Example Contributions

**Adding New Examples**
- Create complete, realistic implementations
- Document step-by-step processes
- Include sample data generators
- Provide validation scripts

**Example Structure**:
```
examples/new-example/
├── README.md                    # Overview and instructions
├── implementation/              # Code and SQL scripts
├── project-setup/              # Requirements and contracts
├── sample-data/                # Data generators
└── validation/                 # Quality check scripts
```

### 🔧 CLI and Tooling

**Improving CLI Functionality**
- Add new commands
- Enhance existing features
- Improve error handling
- Add helpful outputs

**Code Guidelines**:
- Use ES6+ JavaScript
- Follow existing code style
- Add comprehensive error handling
- Include helpful console output

### 📖 Documentation

**Documentation Improvements**
- Enhance README clarity
- Add tutorial content
- Improve code comments
- Create troubleshooting guides

**Documentation Standards**:
- Use clear, concise language
- Include code examples
- Add screenshots where helpful
- Test all instructions

## 🧪 Testing Guidelines

### Running Tests
```bash
# Run framework validation
npm run validate

# Run quality checks
npm run quality-check

# Test CLI functionality
agentic-data info
agentic-data validate
```

### Creating Tests
- Test all new features
- Include edge cases
- Validate data outputs
- Check error conditions

### Test Structure
```bash
# For new examples
cd examples/your-example
python sample-data/generate-sample-data.py
agentic-data validate
# Verify expected outputs
```

## 📝 Code Style Guidelines

### JavaScript/Node.js
- Use ES6+ features
- Follow existing indentation (2 spaces)
- Use meaningful variable names
- Add JSDoc comments for functions

```javascript
/**
 * Validate agent configuration
 * @param {string} agentPath - Path to agent YAML file
 * @returns {Object} Validation result
 */
async function validateAgent(agentPath) {
  // Implementation
}
```

### Python
- Follow PEP 8 style guide
- Use type hints where appropriate
- Add docstrings for functions
- Use meaningful variable names

```python
def validate_data_quality(df: pd.DataFrame) -> Dict[str, Any]:
    """
    Validate data quality using 3-dimensional framework
    
    Args:
        df: DataFrame to validate
        
    Returns:
        Dictionary with validation results
    """
    # Implementation
```

### SQL
- Use uppercase for keywords
- Consistent indentation
- Clear table aliases
- Commented sections

```sql
-- Customer Segmentation Analysis
SELECT 
    c.customer_id,
    c.first_name,
    COUNT(o.order_id) as total_orders,
    SUM(o.total_amount) as total_spent
FROM customers c
LEFT JOIN orders o ON c.customer_id = o.customer_id
WHERE o.status = 'completed'
GROUP BY c.customer_id, c.first_name
ORDER BY total_spent DESC;
```

### YAML
- Consistent 2-space indentation
- Clear, descriptive keys
- Logical grouping
- Inline comments where helpful

```yaml
# Agent metadata
agent_metadata:
  name: "Data Engineer"
  role: "Pipeline Development"
  
# Core capabilities
core_capabilities:
  - "ETL pipeline design"
  - "Data infrastructure setup"
```

## 🐛 Bug Reports

### Before Reporting
- Check existing issues for duplicates
- Test with latest version
- Try to reproduce consistently
- Check documentation for solutions

### Bug Report Template
```
## Bug Description
Brief description of the issue

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- Framework version: [version]
- Node.js version: [version]
- Operating system: [OS and version]
- Additional context

## Additional Information
- Error messages
- Screenshots (if applicable)
- Relevant configuration files
```

## ✨ Feature Requests

### Feature Request Template
```
## Feature Description
Clear description of the requested feature

## Use Case
Why this feature would be valuable

## Proposed Implementation
Ideas for how this could be implemented

## Additional Context
Any other relevant information
```

## 🔍 Review Process

### Pull Request Guidelines
1. **Clear Title**: Descriptive title explaining the change
2. **Detailed Description**: What changes were made and why
3. **Testing**: Evidence that changes work as expected
4. **Documentation**: Update docs if needed
5. **Small Commits**: Keep changes focused and atomic

### Pull Request Template
```
## Changes Made
- Change 1
- Change 2
- Change 3

## Testing
- [ ] Validated with `agentic-data validate`
- [ ] Tested CLI functionality
- [ ] Verified examples work
- [ ] Updated documentation

## Related Issues
Fixes #123
Related to #456

## Additional Notes
Any other relevant information
```

### Review Criteria
- Code quality and style
- Functionality and testing
- Documentation updates
- Community Edition scope (not enterprise features)

## 🏆 Recognition

### Contributors
All contributors are recognized in:
- Repository contributor list
- Release notes
- Community announcements

### Contribution Types
- 🐛 Bug fixes
- ✨ New features
- 📖 Documentation
- 🧪 Testing
- 💡 Ideas and feedback

## 🤝 Community Guidelines

### Code of Conduct
- Be respectful and inclusive
- Welcome newcomers
- Provide constructive feedback
- Focus on improving the framework

### Communication
- Use GitHub Issues for bugs and features
- Use GitHub Discussions for questions
- Be patient with response times
- Provide clear, helpful information

## 📞 Getting Help

### Where to Ask Questions
1. **GitHub Discussions**: General questions and community help
2. **GitHub Issues**: Bug reports and feature requests
3. **Documentation**: Check existing guides first

### Contribution Questions
If you're unsure about contributing:
- Open a discussion to propose ideas
- Comment on existing issues
- Ask for guidance on implementation approaches

## 🎯 Priority Areas

We especially welcome contributions in:
- **Additional Examples**: More industry use cases
- **Template Improvements**: Enhanced existing templates
- **Documentation**: Better tutorials and guides
- **Quality Validation**: Enhanced validation rules
- **CLI Enhancements**: New commands and features

## 🏢 Enterprise vs Community

### Community Edition Scope
Focus contributions on:
- Core 4-agent functionality
- Essential templates (20 templates)
- 3-dimensional quality framework
- Basic examples and CLI

### Enterprise Features
Do not include in Community Edition:
- Advanced agent personas (beyond core 4)
- ML-enhanced features
- Real-time collaboration
- Advanced compliance automation
- Enterprise-specific templates

## 📜 Legal

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

### Contributor License Agreement
- You have the right to contribute your code
- Your contributions are your original work
- You grant the project rights to use your contributions

---

**Thank you for contributing to the AI Agentic Data Stack Framework Community Edition!**

Together, we're building a powerful, accessible data engineering framework for everyone.

**Questions?** Open a discussion on GitHub or email: community@agenticdatastack.com