cotis-cli 0.1.0-alpha

# Contributing to cotis-cli

Thank you for your interest in contributing to cotis-cli. This repository contains the **plugin host** for Cotis build, check, and run routines. The core UI framework and routine implementations live in sibling repositories — see the [README](README.md#ecosystem).

## Getting started

### Prerequisites

- [Rust](https://rustup.rs/) **stable** toolchain (see `rust-toolchain.toml`)
- `rustfmt` and `clippy` components:

  ```bash
  rustup component add rustfmt clippy
  ```

### Build and test

From the repository root:

```bash
# Format (apply changes)
cargo fmt --all

# Lint
cargo clippy --all-targets -- -D warnings

# Test
cargo test

# Documentation
cargo doc --no-deps
```

These are the same checks run in [CI](.github/workflows/ci.yml). Please make sure they pass locally before opening a pull request.

### Runnable examples

To install and run a routine plugin, use a sibling builder crate such as [cotis-web](https://github.com/igna-778/cotis-web) or [cotis-android](https://github.com/igna-778/cotis-android):

```bash
cotis-cli install path:C:\path\to\cotis-web\cotis-web-builder
cotis-cli run cotis_web_builder -- --output .\dist\web
```

## Making changes

### Scope

- Keep pull requests focused. Prefer several small PRs over one large change.
- Match existing code style and naming in the crate you are editing.
- Avoid drive-by refactors unrelated to the issue you are solving.

### Code style

- Run `cargo fmt --all` before committing. Project settings are in `rustfmt.toml` (Rust 2024 edition, 100-column width).
- Address all Clippy warnings (`-D warnings` in CI).
- Prefer clear, self-documenting code. Add comments only for non-obvious design decisions.

### Tests

- Add or update tests when fixing a bug or changing behavior.
- Unit tests live next to the code they cover (`#[cfg(test)]` modules).
- Doc tests on public APIs are encouraged for install-spec parsing and similar pure helpers.
- Run the full test suite with `cargo test`.

### Documentation

- Update rustdoc for public APIs you add or change.
- Update `README.md` when user-facing behavior, commands, or ecosystem wiring changes.
- Add an entry to `CHANGELOG.md` under **Unreleased** for notable changes.

## Pull request process

1. Fork the repository and create a branch from `main`.
2. Make your changes and ensure CI checks pass locally.
3. Open a pull request against `main` with:
   - A clear summary of **what** changed and **why**
   - Links to related issues, if any
   - Notes on breaking changes or plugin ABI changes
4. Maintainers will review and may request changes. Once approved, your PR will be merged.

### Commit messages

Write concise commit messages in the imperative mood, consistent with existing history:

- `feat: add gh: install source for private releases`
- `fix: correct cache path on Windows`
- `docs: clarify plugin ABI finish_installation`
- `refactor: simplify routine version discovery`

## Versioning and releases

| Crate | Current version |
|-------|-----------------|
| `cotis-cli` | 0.1.0-alpha |

We follow [Semantic Versioning](https://semver.org/). Pre-release versions (`-alpha`, `-beta`, etc.) may include breaking API or plugin ABI changes — check `CHANGELOG.md` before upgrading.

Release tagging and publishing are handled by maintainers. Contributors do not need to bump versions unless asked.

## Where to report issues

| Topic | Where |
|-------|-------|
| CLI host, install, cache, plugin loading | [cotis-cli issues](https://github.com/igna-778/cotis-cli/issues) |
| Core traits, defaults, utils, macros | [cotis issues](https://github.com/igna-778/cotis/issues) |
| Web builder routine | [cotis-web](https://github.com/igna-778/cotis-web) |
| Android builder routine | [cotis-android](https://github.com/igna-778/cotis-android) |
| Security vulnerabilities | See [SECURITY.md](SECURITY.md) |

## License

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