sqrtspace-dotnet/CONTRIBUTING.md

# Contributing to SqrtSpace.SpaceTime

Thank you for your interest in contributing to SqrtSpace.SpaceTime! This document provides guidelines and instructions for contributing to the project.

## Table of Contents

- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Pull Request Process](#pull-request-process)
- [Reporting Issues](#reporting-issues)

## Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct:

- Be respectful and inclusive
- Welcome newcomers and help them get started
- Focus on constructive criticism
- Respect differing viewpoints and experiences

## Getting Started

1. Fork the repository on Gitea
2. Clone your fork locally:
   ```bash
   git clone https://git.marketally.com/YOUR_USERNAME/sqrtspace-dotnet.git
   cd sqrtspace-dotnet/sqrtspace-dotnet
   ```
3. Add the upstream remote:
   ```bash
   git remote add upstream https://git.marketally.com/sqrtspace/sqrtspace-dotnet.git
   ```

## Development Setup

### Prerequisites

- .NET 9.0 SDK or later
- Visual Studio 2022, VS Code, or JetBrains Rider
- Git

### Building the Project

```bash
# Restore dependencies and build
dotnet build

# Run tests
dotnet test

# Pack NuGet packages
./pack-nugets.ps1
```

## How to Contribute

### Types of Contributions

- **Bug Fixes**: Fix existing issues or report new ones
- **Features**: Propose and implement new features
- **Documentation**: Improve documentation, add examples
- **Performance**: Optimize algorithms or memory usage
- **Tests**: Add missing tests or improve test coverage

### Finding Issues to Work On

- Check issues labeled [`good first issue`](https://git.marketally.com/sqrtspace/sqrtspace-dotnet/issues?q=&type=all&state=open&labels=good+first+issue)
- Look for [`help wanted`](https://git.marketally.com/sqrtspace/sqrtspace-dotnet/issues?q=&type=all&state=open&labels=help+wanted) labels
- Review the [project milestones](https://git.marketally.com/sqrtspace/sqrtspace-dotnet/milestones)

## Coding Standards

### C# Style Guidelines

- Follow [.NET coding conventions](https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
- Use meaningful variable and method names
- Keep methods focused and small
- Document public APIs with XML comments

### Project-Specific Guidelines

1. **Memory Efficiency**: Always consider memory usage and space-time tradeoffs
2. **√n Principle**: When implementing algorithms, prefer √n space complexity where applicable
3. **Checkpointing**: Consider adding checkpointing support for long-running operations
4. **External Storage**: Use external storage for large data sets that exceed memory limits

### Example Code Style

```csharp
/// <summary>
/// Sorts a large dataset using √n space complexity
/// </summary>
/// <typeparam name="T">The type of elements to sort</typeparam>
/// <param name="source">The source enumerable</param>
/// <param name="comparer">Optional comparer</param>
/// <returns>Sorted enumerable with checkpointing support</returns>
public static ISpaceTimeEnumerable<T> ExternalSort<T>(
    this IEnumerable<T> source,
    IComparer<T>? comparer = null)
{
    ArgumentNullException.ThrowIfNull(source);
    
    // Implementation following √n space principles
    var chunkSize = (int)Math.Sqrt(source.Count());
    return new ExternalSortEnumerable<T>(source, chunkSize, comparer);
}
```

## Testing

### Test Requirements

- All new features must include unit tests
- Maintain or improve code coverage (aim for >80%)
- Include performance benchmarks for algorithmic changes

### Running Tests

```bash
# Run all tests
dotnet test

# Run specific test project
dotnet test tests/SqrtSpace.SpaceTime.Tests

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"
```

### Writing Tests

```csharp
[Fact]
public void ExternalSort_ShouldHandleLargeDatasets()
{
    // Arrange
    var data = GenerateLargeDataset(1_000_000);
    
    // Act
    var sorted = data.ExternalSort().ToList();
    
    // Assert
    sorted.Should().BeInAscendingOrder();
    sorted.Should().HaveCount(1_000_000);
}
```

## Pull Request Process

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

2. **Make Your Changes**
   - Write clean, documented code
   - Add/update tests
   - Update documentation if needed

3. **Commit Your Changes**
   ```bash
   git add .
   git commit -m "feat: add external sorting with √n space complexity"
   ```
   
   Follow [Conventional Commits](https://www.conventionalcommits.org/):
   - `feat:` New feature
   - `fix:` Bug fix
   - `docs:` Documentation changes
   - `test:` Test additions/changes
   - `perf:` Performance improvements
   - `refactor:` Code refactoring

4. **Push to Your Fork**
   ```bash
   git push origin feature/your-feature-name
   ```

5. **Open a Pull Request**
   - Use a clear, descriptive title
   - Reference any related issues
   - Describe what changes you made and why
   - Include screenshots for UI changes

### PR Checklist

- [ ] Code follows project style guidelines
- [ ] Tests pass locally (`dotnet test`)
- [ ] Added/updated tests for new functionality
- [ ] Updated documentation if needed
- [ ] Checked for breaking changes
- [ ] Benchmarked performance-critical changes

## Reporting Issues

### Bug Reports

When reporting bugs, please include:

1. **Description**: Clear description of the issue
2. **Reproduction Steps**: Minimal code example or steps to reproduce
3. **Expected Behavior**: What should happen
4. **Actual Behavior**: What actually happens
5. **Environment**:
   - SqrtSpace.SpaceTime version
   - .NET version
   - Operating system
   - Relevant hardware specs (for memory-related issues)

### Feature Requests

For feature requests, please include:

1. **Use Case**: Describe the problem you're trying to solve
2. **Proposed Solution**: Your suggested approach
3. **Alternatives**: Other solutions you've considered
4. **Additional Context**: Any relevant examples or references

## Questions?

- Open an [Issue](https://git.marketally.com/sqrtspace/sqrtspace-dotnet/issues)
- Check existing [Issues](https://git.marketally.com/sqrtspace/sqrtspace-dotnet/issues)

## License

By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.

---

Thank you for contributing to SqrtSpace.SpaceTime! Your efforts help make memory-efficient computing accessible to everyone.