# Contributing to secretsh

Thank you for considering contributing to secretsh. This document covers the development workflow, code standards, and how to submit changes.

## Development Setup

```bash
# Clone
git clone https://github.com/lthoangg/secretsh.git
cd secretsh

# Build
cargo build

# Run tests
cargo test

# Lint (must pass with zero warnings)
cargo clippy -- -D warnings

# Format
cargo fmt
```

### Python Bindings

```bash
uv venv .venv && source .venv/bin/activate
uv sync --group dev                      # install pytest, pytest-cov
maturin develop --features python        # build native module into venv
python -m pytest tests/ -v               # run Python tests
```

## Code Standards

### Rust

- **Edition:** 2021
- **MSRV:** 1.75
- **Formatting:** `cargo fmt` (default `rustfmt` settings with the project's `rustfmt.toml`)
- **Linting:** `cargo clippy -- -D warnings` must pass with zero warnings
- **Tests:** All existing tests must pass. New functionality requires tests.

### Security-Sensitive Code

This is a security tool. Extra care is required:

- **All secret data** must be wrapped in `zeroize::Zeroizing<Vec<u8>>`. Never use `String` for secret values.
- **No `println!` or `dbg!`** with secret data. Use `[REDACTED]` in debug output.
- **Unsafe code** requires a `// SAFETY:` comment explaining why it is sound.
- **New syscalls** require documentation of failure modes and graceful degradation behavior.
- **Tokenizer changes** are high-risk. Any modification to `tokenizer.rs` must include corresponding test cases and should be fuzz-tested.

### Commit Messages

Write concise commit messages that explain **why**, not just what:

```
fix: reject bare $ before { in tokenizer

Previously, `${ VAR}` was not caught as variable expansion because
the space between `{` and `V` broke the pattern match. The tokenizer
now rejects `${` regardless of what follows.
```

Use conventional commit prefixes: `fix:`, `feat:`, `refactor:`, `test:`, `docs:`, `ci:`, `chore:`.

## Submitting Changes

1. **Fork** the repository.
2. **Create a branch** from `main`: `git checkout -b fix/tokenizer-dollar-brace`.
3. **Make your changes** with tests.
4. **Run the full check suite:**
   ```bash
   cargo fmt --check
   cargo clippy -- -D warnings
   cargo test
   ```
5. **Open a Pull Request** against `main`.

### PR Checklist

- [ ] `cargo fmt --check` passes
- [ ] `cargo clippy -- -D warnings` passes
- [ ] `cargo test` passes (all existing + new tests)
- [ ] `python -m pytest tests/` passes (if Python bindings are affected)
- [ ] New public APIs have doc comments
- [ ] Security-sensitive changes have corresponding test coverage
- [ ] Commit messages follow the conventional format

## Reporting Bugs

Open a [GitHub Issue](https://github.com/lthoangg/secretsh/issues) with:

- secretsh version (`secretsh --version`)
- OS and architecture
- Steps to reproduce
- Expected vs actual behavior

For security vulnerabilities, see [SECURITY.md](SECURITY.md) instead.

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
