Skip to content

Latest commit

 

History

History
113 lines (77 loc) · 4.07 KB

CONTRIBUTING.md

File metadata and controls

113 lines (77 loc) · 4.07 KB

Contributing to soft-canonicalize

Thanks for your interest in contributing! 🦀

Quick Start

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR_USERNAME/soft-canonicalize-rs.git
  3. Test locally:
    • Linux/macOS/WSL: bash ci-local.sh
    • Windows PowerShell: .\ci-local.ps1
    • Both scripts run all CI checks including security audit
  4. Submit a pull request

All PRs automatically run CI on Windows, Linux, and macOS with security auditing.

How to Contribute

  • 🐛 Bug reports: Open an issue with reproduction steps
  • 💡 Features: Discuss in an issue before implementing
  • 📝 Docs: Fix typos, add examples, improve clarity
  • 🔧 Code: Bug fixes and improvements welcome

Development

Project Philosophy:

  • std compatibility - Match std::fs::canonicalize behavior for existing paths
  • Zero dependencies - Keep it lightweight
  • Cross-platform - Windows, Linux, macOS
  • Security focused - Proper symlink and .. handling with automated security auditing
  • Pure algorithm - No filesystem modification

AI Prompt

Copy-paste this when working with AI on this project:

Rules: Always run `bash ci-local.sh` or `.\ci-local.ps1` before committing. This project must maintain 100% behavioral compatibility with std::fs::canonicalize for existing paths while extending to non-existing paths. Never remove existing APIs, tests, or break std compatibility. All std library compatibility tests must continue to pass. Preserve security features like symlink cycle detection and security auditing. Avoid redundant explanations in documentation.

What We Want ✅

  • Bug fixes and performance improvements
  • Better error handling and documentation
  • Cross-platform compatibility fixes
  • Additional security tests and examples
  • std library compatibility improvements

What We Don't Want ❌

  • Breaking changes to std compatibility (discuss first)
  • New dependencies (unless strongly justified)
  • Behavior changes that break existing tests
  • Features that compromise security

Testing

Simple: Just run the CI script locally:

# Linux/macOS/WSL
bash ci-local.sh

# Windows PowerShell  
.\ci-local.ps1

This runs all checks (format, clippy, tests, docs, security audit, MSRV) and ensures std compatibility. If it passes, your code is ready.

Test Coverage: The project has 301 tests total:

  • 78 unit tests (in src/tests/)
  • 6 complex attack tests (blackbox security)
  • 9 security tests (comprehensive security coverage)
  • 11 compatibility tests (std library compatibility)
  • 164 integration tests (in tests/ directory)
  • 4 documentation tests
  • 8 anchored canonicalization tests (with --features anchored)

The CI runs tests in both default and all-features configurations.

Project Structure:

  • src/ - Main library code and unit tests
  • examples/ - User-facing examples (essential examples only)
  • examples/archive/ - Historical examples from optimization work
  • benches/ - Performance benchmarks vs Python baseline
  • benches/python/ - Historical Python investigation scripts
  • tests/ - Integration and blackbox security tests

Benchmarks: Performance benchmarks are in benches/ and can be run with cargo bench. See benches/README.md for details (Linux/WSL prefers python3.13 for baseline; use 5-run median protocol).

Performance Testing: See benches/README.md for a step-by-step guide and the 5-run median protocol.

Examples: See examples/ directory for usage examples and demonstrations.

License

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

You confirm that:

  • You have the right to submit your contribution
  • Your contribution is your original work or properly attributed

Getting Help

Every contribution matters! 🚀