# 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](https://rustup.rs/)
- **Python**: Python 3.10 or later for Python bindings testing
- **Git**: For version control
### Setting Up Your Development Environment
1. **Fork and clone the repository**:
- First, fork the repository on GitHub by clicking the "Fork" button at [github.com/ssmichael1/satkit](https://github.com/ssmichael1/satkit)
- Then clone your fork:
```bash
git clone https://github.com/YOUR-USERNAME/satkit.git
cd satkit
```
- Add the original repository as an upstream remote:
```bash
git remote add upstream https://github.com/ssmichael1/satkit.git
```
2. **Download test vectors and data files**:
```bash
python -m pip install requests
python ./python/test/download_testvecs.py
```
3. **Build the project**:
```bash
cargo build
```
4. **Run the tests**:
```bash
cargo test
```
## Development Workflow
### Making Changes
1. **Create a new branch** for your feature or fix:
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes** following the code style guidelines below
3. **Test your changes**:
```bash
cargo test
cargo clippy -- -D warnings
cargo fmt --check
```
4. **Commit your changes** with clear, descriptive commit messages:
```bash
git commit -m "Add feature: brief description"
```
5. **Push to your fork**:
```bash
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](https://rust-lang.github.io/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](https://pep8.org/) 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
### Changelog
- Add **one user-facing line** per pull request under `## Unreleased` in
`CHANGELOG.md`, in the matching `Added` / `Changed` / `Fixed` / `CI`
section, ending with the PR link, e.g. `([#127](https://github.com/ssmichael1/satkit/pull/127))`.
- Keep it to two lines at most: what changed and, if useful, the one number
that says why it matters. Implementation detail, measurements and rationale
belong in the pull-request description — PRs are squash-merged, so that
description becomes the commit message on `main` and is the permanent record.
- Mark breaking changes in bold (`**Breaking:**`).
- At release time, rename `Unreleased` to the version and date and prune the
file so it keeps the last five releases. Older entries stay in git history
(`git show vX.Y.Z:CHANGELOG.md`); there is no archive file.
## 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](https://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](https://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:
```bash
# 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/
```
When you're done developing, deactivate the virtual environment:
```bash
deactivate
```
## Running Tests
### Full Test Suite
```bash
cargo test
```
### Specific Test Module
```bash
cargo test ode::ode_tests
```
### With Output
```bash
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 (editable install, Python 3.13) and checks the `.pyi` stubs with stubtest; release builds smoke-test each published wheel (3.10–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 squash-merge your contribution (one commit per PR; the PR description becomes the commit message)
4. Your changes will be included in the next release
## Licensing
Satkit is dual-licensed under the MIT license ([LICENSE-MIT](LICENSE-MIT)) and the Apache License, Version 2.0 ([LICENSE-APACHE](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?
- **Open a GitHub Issue** at [github.com/ssmichael1/satkit/issues](https://github.com/ssmichael1/satkit/issues) for questions about contributing
- Email the maintainer: ssmichael@gmail.com
- Review existing issues and pull requests for examples
- Check the documentation at [satkit.dev](https://satkit.dev/)
## Resources
- [Rust Book](https://doc.rust-lang.org/book/)
- [PyO3 Documentation](https://pyo3.rs/)
- [Cargo Book](https://doc.rust-lang.org/cargo/)
- [GitHub Flow](https://guides.github.com/introduction/flow/)
Thank you for contributing to Satkit! 🛰️