Initial push
This commit is contained in:
234
CONTRIBUTING.md
Normal file
234
CONTRIBUTING.md
Normal file
@@ -0,0 +1,234 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user