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
• Getting Started
• Development Setup
• How to Contribute
• Coding Standards
• Testing
• Pull Request Process
• 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:

   git clone https://git.marketally.com/YOUR_USERNAME/sqrtspace-dotnet.git
   cd sqrtspace-dotnet/sqrtspace-dotnet
   

3. Add the upstream remote:

   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

# 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
• Look for help wanted labels
• Review the project milestones

Coding Standards

C# Style Guidelines

• Follow .NET 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

/// <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

# 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

[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

   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

   git add .
   git commit -m "feat: add external sorting with √n space complexity"
   

   Follow Conventional Commits:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation changes
   • test: Test additions/changes
   • perf: Performance improvements
   • refactor: Code refactoring

4. Push to Your Fork

   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
• Check existing 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.