network/CONTRIBUTING.md

Contributing to DebrosFramework

Thank you for your interest in contributing to DebrosFramework! This document provides guidelines and information for contributors.

Development Status

DebrosFramework is currently in beta (v0.5.0-beta) and under active development. We welcome contributions from the community to help improve the framework.

Getting Started

Prerequisites

• Node.js 18.0 or higher
• npm or pnpm package manager
• Git
• TypeScript knowledge
• Familiarity with IPFS and OrbitDB concepts

Development Setup

1. Fork and Clone

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

2. Install Dependencies

   pnpm install
   

3. Build the Project

   pnpm run build
   

4. Run Tests

   # Unit tests
   pnpm run test:unit
   
   # Integration tests
   pnpm run test:real
   

Project Structure

src/framework/
├── core/           # Core framework components
├── models/         # Model system and decorators
├── query/          # Query builder and execution
├── relationships/  # Relationship management
├── sharding/       # Data sharding logic
├── migrations/     # Schema migration system
├── pinning/        # Automatic pinning features
├── pubsub/         # Event publishing system
└── types/          # TypeScript type definitions

docs/docs/          # Documentation source
tests/              # Test suites
└── real-integration/ # Integration test scenarios

How to Contribute

Types of Contributions

We welcome the following types of contributions:

1. 🐛 Bug Reports - Report issues and bugs
2. ✨ Feature Requests - Suggest new features
3. 📖 Documentation - Improve docs and examples
4. 🔧 Code Contributions - Bug fixes and new features
5. 🧪 Testing - Add tests and improve test coverage
6. 💡 Examples - Create usage examples and tutorials

Bug Reports

When reporting bugs, please include:

• Clear description of the issue
• Steps to reproduce the problem
• Expected vs actual behavior
• Environment details (Node.js version, OS, etc.)
• Code examples that demonstrate the issue
• Error messages and stack traces

Use our bug report template:

## Bug Description

[Clear description of the bug]

## Steps to Reproduce

1. [First step]
2. [Second step]
3. [etc.]

## Expected Behavior

[What you expected to happen]

## Actual Behavior

[What actually happened]

## Environment

- DebrosFramework version: [version]
- Node.js version: [version]
- OS: [operating system]

## Code Example

```typescript
// Minimal code example that reproduces the issue
```

### Feature Requests

For feature requests, please provide:

- **Clear use case** and motivation
- **Detailed description** of the proposed feature
- **API design suggestions** (if applicable)
- **Examples** of how it would be used
- **Alternatives considered**

### Code Contributions

#### Before You Start

1. **Check existing issues** to avoid duplicate work
2. **Discuss large changes** in an issue first
3. **Follow the coding standards** outlined below
4. **Write tests** for your changes
5. **Update documentation** as needed

#### Development Workflow

1. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name

2. Make your changes

   • Write clean, well-documented code
   • Follow TypeScript best practices
   • Add tests for new functionality
   • Update relevant documentation

3. Test your changes

   pnpm run test:unit
   pnpm run test:real
   pnpm run lint
   

4. Commit your changes

   git add .
   git commit -m "feat: add new feature description"
   

5. Push and create PR

   git push origin feature/your-feature-name
   

Commit Message Format

We use conventional commits for consistent commit messages:

type(scope): description

body (optional)

footer (optional)

Types:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat(models): add support for computed fields
fix(query): resolve relationship loading issue
docs(readme): update installation instructions

Code Style Guidelines

1. TypeScript

   • Use strict TypeScript configuration
   • Provide proper type annotations
   • Use interfaces for object types
   • Follow naming conventions

2. Formatting

   • Use Prettier for code formatting
   • Run pnpm run format before committing
   • Use 2 spaces for indentation

3. ESLint

   • Follow ESLint rules
   • Run pnpm run lint and fix any issues
   • Use pnpm run lint:fix for auto-fixes

4. Documentation

   • Add JSDoc comments for public APIs
   • Update relevant documentation files
   • Include code examples where appropriate

Testing Guidelines

1. Unit Tests

   • Write tests for all new functionality
   • Use Jest for unit testing
   • Aim for high code coverage
   • Test edge cases and error conditions

2. Integration Tests

   • Add integration tests for significant features
   • Test real-world scenarios
   • Use the blog scenario tests as reference

3. Test Structure

   describe('FeatureName', () => {
     beforeEach(() => {
       // Setup
     });
   
     it('should behave correctly in normal case', () => {
       // Test implementation
     });
   
     it('should handle edge case', () => {
       // Edge case test
     });
   
     it('should throw error for invalid input', () => {
       // Error case test
     });
   });
   

Documentation

Documentation Structure

• README.md - Overview and quick start
• docs/docs/intro.md - Framework introduction
• docs/docs/getting-started.md - Setup guide
• docs/docs/core-concepts/ - Architecture and concepts
• docs/docs/api/ - API reference
• docs/docs/examples/ - Usage examples

Writing Documentation

1. Use clear, concise language
2. Provide code examples
3. Include both basic and advanced usage
4. Keep examples up-to-date
5. Add diagrams where helpful

Building Documentation

cd docs
npm install
npm run start  # Development server
npm run build  # Production build

Release Process

Releases are managed by the core team and follow semantic versioning:

• Patch (0.5.1): Bug fixes and small improvements
• Minor (0.6.0): New features, backward compatible
• Major (1.0.0): Breaking changes

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

• Be respectful and considerate
• Use inclusive language
• Accept constructive feedback
• Focus on what's best for the community
• Show empathy towards other contributors

Getting Help

• GitHub Issues - For bug reports and feature requests
• GitHub Discussions - For questions and community discussion
• Discord - For real-time chat and support

Recognition

Contributors will be recognized in:

• CONTRIBUTORS.md file
• Release notes for significant contributions
• Documentation credits for doc contributions

Questions?

If you have questions about contributing, please:

1. Check existing documentation
2. Search GitHub issues
3. Ask in GitHub Discussions
4. Contact the maintainers

Thank you for contributing to DebrosFramework! 🚀