# Contributing to RustShell
Thank you for your interest in contributing to RustShell! This document provides guidelines and instructions for contributing to the project.
## Table of Contents
- [Getting Started](#getting-started)
- [Building and Testing](#building-and-testing)
- [Code Style](#code-style)
- [Pull Request Process](#pull-request-process)
- [Plugin Development](#plugin-development)
- [Reporting Issues](#reporting-issues)
## Getting Started
1. Fork the repository on GitHub
2. Clone your fork locally:
```bash
git clone https://github.com/YOUR_USERNAME/rustshell.git
cd rustshell
```
3. Add the upstream repository:
```bash
git remote add upstream https://github.com/efebarandurmaz/rustshell.git
```
## Building and Testing
### Prerequisites
- Rust 1.70 or later (stable toolchain)
- Git
### Building
Build the project in debug mode:
```bash
cargo build
```
Build in release mode with optimizations:
```bash
cargo build --release
```
### Running Tests
Run all tests:
```bash
cargo test
```
Run tests with output:
```bash
cargo test -- --nocapture
```
Run specific test:
```bash
cargo test test_name
```
### Running the Shell
Run in development mode:
```bash
cargo run
```
Run with arguments:
```bash
cargo run -- --mode dry-run "list all rust files"
```
## Code Style
RustShell follows standard Rust coding conventions enforced by `rustfmt` and `clippy`.
### Formatting
Before committing, ensure your code is properly formatted:
```bash
cargo fmt
```
Check formatting without modifying files:
```bash
cargo fmt --check
```
### Linting
Run clippy to catch common mistakes and improve code quality:
```bash
cargo clippy
```
Clippy warnings are treated as errors in CI. Fix all clippy warnings before submitting:
```bash
cargo clippy -- -D warnings
```
### Code Guidelines
- Use meaningful variable and function names
- Add documentation comments (`///`) for public APIs
- Write tests for new functionality
- Keep functions focused and small
- Avoid unwrap() in production code; use proper error handling
- Use `#[serde(default)]` for all new config fields to ensure backward compatibility
## Pull Request Process
1. **Create a feature branch** from `master`:
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes** following the code style guidelines
3. **Write or update tests** for your changes
4. **Ensure all tests pass** and code is formatted:
```bash
cargo test
cargo fmt
cargo clippy -- -D warnings
```
5. **Commit your changes** with clear, descriptive commit messages:
```bash
git commit -m "feat: add support for XYZ"
```
Follow conventional commit format:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `refactor:` - Code refactoring
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks
- `ci:` - CI/CD changes
6. **Push to your fork**:
```bash
git push origin feature/your-feature-name
```
7. **Open a Pull Request** on GitHub with:
- Clear title describing the change
- Description explaining what and why
- Reference any related issues
- Screenshots (if UI changes)
8. **Address review feedback** - maintainers may request changes
9. **Squash commits** if requested before merge
## Plugin Development
RustShell supports subprocess-based plugins following the git/kubectl pattern.
### Plugin Requirements
1. **Naming**: Plugins must be named `rustshell-plugin-<name>`
2. **Executable**: Must be a standalone executable (any language)
3. **Manifest**: Must respond to `--rustshell-manifest` flag
4. **Location**: Place in `~/.rustshell/plugins/` or anywhere on `$PATH`
### Manifest Format
Your plugin must output a JSON manifest when called with `--rustshell-manifest`:
```json
{
"name": "example",
"version": "0.1.0",
"description": "Example plugin for RustShell",
"commands": [
{
"name": "hello",
"description": "Say hello"
},
{
"name": "goodbye",
"description": "Say goodbye"
}
]
}
```
### Example Plugin (Python)
```python
#!/usr/bin/env python3
import sys
import json
MANIFEST = {
"name": "example",
"version": "0.1.0",
"description": "Example plugin",
"commands": [
{"name": "hello", "description": "Say hello"}
]
}
if __name__ == "__main__":
if len(sys.argv) > 1 and sys.argv[1] == "--rustshell-manifest":
print(json.dumps(MANIFEST))
sys.exit(0)
if len(sys.argv) > 1 and sys.argv[1] == "hello":
print("Hello from example plugin!")
sys.exit(0)
print("Unknown command", file=sys.stderr)
sys.exit(1)
```
### Plugin Installation
1. Make your plugin executable:
```bash
chmod +x rustshell-plugin-example
```
2. Place it in the plugin directory:
```bash
mkdir -p ~/.rustshell/plugins
cp rustshell-plugin-example ~/.rustshell/plugins/
```
3. Verify it's discovered:
```bash
rustshell
> plugin list
```
### Plugin Best Practices
- Handle errors gracefully and return appropriate exit codes
- Use stderr for error messages, stdout for output
- Support `--help` for command documentation
- Keep plugin commands focused and simple
- Test your plugin on all target platforms
- Document dependencies and installation steps
## Reporting Issues
When reporting issues, please include:
1. **Environment information**:
- Operating system and version
- Rust version (`rustc --version`)
- RustShell version (`rustshell --version`)
2. **Steps to reproduce** the issue
3. **Expected behavior** vs actual behavior
4. **Error messages** or logs (if applicable)
5. **Configuration** (sanitize any API keys):
```bash
cat ~/.rustshell/config.toml
```
## Development Tips
### Testing with Different LLM Providers
Create a `.env` file in the project root:
```bash
OPENAI_API_KEY=your-key-here
GROQ_API_KEY=your-key-here
ANTHROPIC_API_KEY=your-key-here
```
### Testing in Dry-Run Mode
Use dry-run mode to test NLP translation without executing:
```bash
cargo run -- --mode dry-run "your natural language command"
```
### Debugging
Enable debug logging:
```bash
RUST_LOG=debug cargo run
```
### Testing Cross-Platform
Use GitHub Actions to test on all platforms, or use Docker/VMs locally.
## License
By contributing to RustShell, you agree that your contributions will be licensed under the MIT License.
## Questions?
Feel free to open an issue for questions or join discussions in the GitHub Discussions section.
Thank you for contributing to RustShell!