234 lines
6.3 KiB
Markdown
234 lines
6.3 KiB
Markdown
# 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 GitHub
|
|
2. Clone your fork locally:
|
|
```bash
|
|
git clone https://github.com/YOUR_USERNAME/sqrtspace-dotnet.git
|
|
cd sqrtspace-dotnet/sqrtspace-dotnet
|
|
```
|
|
3. Add the upstream remote:
|
|
```bash
|
|
git remote add upstream https://github.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://github.com/sqrtspace/sqrtspace-dotnet/labels/good%20first%20issue)
|
|
- Look for [`help wanted`](https://github.com/sqrtspace/sqrtspace-dotnet/labels/help%20wanted) labels
|
|
- Review the [project roadmap](https://github.com/sqrtspace/sqrtspace-dotnet/projects)
|
|
|
|
## 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 a [Discussion](https://github.com/sqrtspace/sqrtspace-dotnet/discussions)
|
|
- Check existing [Issues](https://github.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. |