Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
225 lines (158 loc) · 6.28 KB

CONTRIBUTING.md

File metadata and controls

225 lines (158 loc) · 6.28 KB

Contributing to Satkit

Thank you for your interest in contributing to Satkit! This document provides guidelines and information for contributors.

Getting Started

Prerequisites

  • Rust: Install the latest stable Rust toolchain from rustup.rs
  • Python: Python 3.8 or later for Python bindings testing
  • Git: For version control

Setting Up Your Development Environment

  1. Fork and clone the repository:

    git clone https://github.com/YOUR-USERNAME/satkit.git
cd satkit
    • Add the original repository as an upstream remote:
    git remote add upstream https://github.com/ssmichael1/satkit.git

  2. Download test vectors and data files:

    python -m pip install requests
python ./python/test/download_testvecs.py

  3. Build the project:

    cargo build

  4. Run the tests:

    cargo test

Development Workflow

Making Changes

  1. Create a new branch for your feature or fix:

    git checkout -b feature/your-feature-name

  2. Make your changes following the code style guidelines below

  3. Test your changes:

    cargo test
cargo clippy -- -D warnings
cargo fmt --check

  4. Commit your changes with clear, descriptive commit messages:

    git commit -m "Add feature: brief description"

  5. Push to your fork:

    git push origin feature/your-feature-name

  6. Open a Pull Request on GitHub with a clear description of your changes

Code Style and Standards

Rust Code

  • Follow the Rust API Guidelines
  • Use cargo fmt to format your code (runs automatically in CI)
  • Ensure cargo clippy passes without warnings
  • Write documentation comments (///) for all public APIs
  • Include examples in documentation where appropriate

Python Bindings

  • Follow PEP 8 style guidelines
  • Provide type hints in .pyi stub files for IDE support
  • Include docstrings for all public functions and classes
  • Test Python bindings separately when making changes ; see python/test/test.py

Testing

  • Write unit tests for all new functionality
  • Add integration tests for complex features
  • Ensure existing tests continue to pass
  • Add test cases from published references when available (Vallado, JPL, etc.)

Documentation

  • Update relevant documentation for API changes
  • Add examples for new features
  • Keep README.md up to date with new capabilities
  • Document any breaking changes clearly

Types of Contributions

Bug Reports

When you encounter a bug, please help us fix it by:

  1. Opening a GitHub Issue at github.com/ssmichael1/satkit/issues
  2. Include a minimal reproducible example
  3. Specify your environment (OS, Rust version, Python version if applicable)
  4. Describe expected vs actual behavior
  5. Add relevant error messages or stack traces

Feature Requests

If you have a suggestion for a feature:

  1. Open a GitHub Issue at github.com/ssmichael1/satkit/issues
  2. Use a clear, descriptive title
  3. Explain the use case and potential benefits
  4. Describe the proposed solution or API
  5. Consider backward compatibility
  6. Tag the issue with the enhancement label if possible

Note: Please open an issue to discuss significant new features before implementing them. This helps ensure alignment with project goals and avoids duplicated effort.

Code Contributions

We welcome contributions in these areas:

High Priority

  • Bug fixes and correctness improvements
  • Performance optimizations
  • Additional test coverage
  • Documentation enhancements

New Features

  • See issues in github page for current list

Building Python Bindings

To build and test the Python package locally:

# Create and activate a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install build dependencies and test
pip install setuptools setuptools-rust setuptools-scm pytest

# Build and install in development mode
pip install -e .

# Run Python tests
python -m pytest python/test/test.py

When you're done developing, deactivate the virtual environment:

deactivate

Running Tests

Full Test Suite

cargo test

Specific Test Module

cargo test ode::ode_tests

With Output

cargo test -- --nocapture

Continuous Integration

All pull requests are automatically tested via GitHub Actions:

  • Build: Compiles on Linux, macOS, and Windows
  • Test: Runs full test suite on all platforms
  • Lint: Checks code style with clippy
  • Format: Verifies formatting with rustfmt
  • Python: Tests Python bindings on all supported versions (3.8-3.14)

Ensure all CI checks pass before requesting review.

Code Review Process

  1. Maintainers will review your pull request
  2. Address any feedback or requested changes
  3. Once approved, maintainers will merge your contribution
  4. Your changes will be included in the next release

Licensing

Satkit is dual-licensed under the MIT license (LICENSE-MIT) and the Apache License, Version 2.0 (LICENSE-APACHE). Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Satkit by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Questions?

Resources

Thank you for contributing to Satkit! 🛰️