# Contributing
Contributions to Torc are welcome! This guide will help you get started.
## Development Setup
1. **Fork and clone the repository:**
```bash
git clone https://github.com/your-username/torc.git
cd torc
```
2. **Install Rust and dependencies:**
Make sure you have Rust 1.85 or later installed:
```bash
3. **Install cargo-nextest:**
```bash
cargo install cargo-nextest
```
4. **Install SQLx CLI:**
```bash
cargo install sqlx-cli --no-default-features --features sqlite
```
5. **Set up the database:**
```bash
# Create .env file
echo "DATABASE_URL=sqlite:torc.db" > .env
# Run migrations
sqlx migrate run --source torc-server/migrations
```
6. **Build and test:**
```bash
cargo build
cargo nextest run --all-features
```
## Making Changes
### Code Style
Run formatting and linting before committing:
```bash
# Format code
cargo fmt
# Run clippy
cargo clippy --all --all-targets --all-features -- -D warnings
# Run all checks
cargo fmt --check && cargo clippy --all --all-targets --all-features -- -D warnings
```
### Adding Tests
All new functionality should include tests:
```bash
# Run specific test
cargo nextest run -E 'test(test_name)'
# Run with logging
RUST_LOG=debug cargo nextest run -E 'test(test_name)'
```
### Database Migrations
If you need to modify the database schema:
```bash
# Create new migration
sqlx migrate add --source torc-server/migrations <migration_name>
# Edit the generated SQL file in torc-server/migrations/
# Run migration
sqlx migrate run --source torc-server/migrations
# To revert
sqlx migrate revert --source torc-server/migrations
```
## Submitting Changes
1. **Create a feature branch:**
```bash
git checkout -b feature/my-new-feature
```
2. **Make your changes and commit:**
```bash
git add .
git commit -m "Add feature: description"
```
3. **Ensure all tests pass:**
```bash
cargo nextest run --all-features
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
```
4. **Push to your fork:**
```bash
git push origin feature/my-new-feature
```
5. **Open a Pull Request:**
Go to the original repository and open a pull request with:
- Clear description of changes
- Reference to any related issues
- Test results
## Pre-Release: Slurm Integration Tests
Before tagging a release, run the Slurm integration test suite on an HPC cluster to verify that job
submission, multi-node execution, failure recovery, and resource monitoring work correctly under a
real Slurm scheduler.
### Prerequisites
- Access to an HPC cluster with Slurm
- `torc`, `torc-server`, and `torc-htpasswd` binaries built
(`cargo build --release
--all-features`)
- `jq` and Slurm CLI tools (`sbatch`, etc.) available on the login node
### Running the Suite
From the repository root on a login node:
```bash
./slurm-tests/run_all.sh --account <SLURM_ACCOUNT> --host <LOGIN_NODE_HOSTNAME>
```
Common options:
```bash
# Use a specific partition (default: debug)
./slurm-tests/run_all.sh --account myproject --host login1.hpc.example.com \
--partition gpu
# Run a single test by name substring
./slurm-tests/run_all.sh --account myproject --host login1.hpc.example.com \
--test oom_detection
# Adjust timeout and parallelism
./slurm-tests/run_all.sh --account myproject --host login1.hpc.example.com \
--timeout 60 --max-parallel-jobs 8
```
The runner starts a temporary Torc server, executes each test as a child workflow under Slurm, and
writes results to `slurm-tests/output/run_<timestamp>/results.json`. All tests must pass before a
release is tagged.
## Pull Request Guidelines
- **Keep PRs focused** - One feature or fix per PR
- **Add tests** - All new code should be tested
- **Update documentation** - Update README.md, DOCUMENTATION.md, or inline docs as needed
- **Follow style guidelines** - Run `cargo fmt` and `cargo clippy`
- **Write clear commit messages** - Describe what and why, not just how
## Areas for Contribution
### High Priority
- Performance optimizations for large workflows
- Additional job runner implementations (Kubernetes, etc.)
- Improved error messages and logging
- Documentation improvements
### Features
- Workflow visualization tools
- Job retry policies and error handling
- Workflow templates and libraries
- Integration with external systems
### Testing
- Additional integration tests
- Performance benchmarks
- Stress testing with large workflows
## Code of Conduct
Be respectful and constructive in all interactions. We're all here to make Torc better.
## Questions?
- Open an issue for bugs or feature requests
- Start a discussion for questions or ideas
- Check existing issues and discussions first
## License
By contributing, you agree that your contributions will be licensed under the BSD 3-Clause License.