# Contributing to `dsc`

Thanks for thinking about contributing. `dsc` is a small but actively-shaped project; the bar for landing changes is "useful, tested, narrow, and follows the existing patterns." This file points you at the right entry points and conventions.

## Quick orientation

| You want to … | Read |
|---|---|
| Build and test the project locally | [docs/development.md](docs/development.md) |
| Understand the CLI design standards | [spec/spec.md](spec/spec.md) |
| Use `dsc` to manage a real Discourse | [docs/](docs/) (per-command pages) |
| Use `dsc` from another LLM/agent session | [AGENTS.md](AGENTS.md) |
| File a feature request | See **"Filing issues"** below |
| Propose a substantial new command | Write a spec - see [AGENTS.md - "What makes a spec land fast"](AGENTS.md#what-makes-a-spec-land-fast) |

## Reporting bugs vs filing specs

- **Bug** — something `dsc` claims to do but does wrong. Open a [bug issue](.github/ISSUE_TEMPLATE/bug_report.md) with the exact command, expected vs actual, and `dsc version`.
- **Small feature request** — a flag, a tweak to existing output, a missing subcommand alias. Open a [feature issue](.github/ISSUE_TEMPLATE/feature_request.md).
- **Substantial new command or surface** — write a spec under [spec/](spec/) before code, using the [spec template in AGENTS.md](AGENTS.md#spec-template). Open a [spec issue](.github/ISSUE_TEMPLATE/spec_request.md) linking the draft if you'd like discussion first.

When in doubt, file the spec - it captures more context and the author can shrink it to an issue if it's smaller than it looks.

## Code contributions

### Setup

```bash
git clone https://github.com/pacharanero/dsc.git
cd dsc
cargo build
cargo test
```

### Conventions

- **Conventional commits.** `feat(area):`, `fix(area):`, `docs:`, `chore(deps):`, `ci(deps):`, etc. Used since v0.9; the `CHANGELOG.md` generator relies on this shape.
- **Tests.** Every new command path gets a unit test for the pure logic and (where it talks to Discourse) a test in `tests/` that exercises the public CLI. See `tests/topic-test.rs` for the shape.
- **Docs.** A new subcommand requires:
  - help text on the CLI (`#[arg(help = …)]` or doc-comment)
  - a section in the matching `docs/<command>.md`
  - a row in [README.md](README.md) "Documentation" if it's a new top-level command
- **No version-bump commits without a feature** — `s/version++ patch` is for release-worthy changes, not docs polish. Pure docs commits use `docs:` prefix and no bump.

### Pull requests

- Keep PRs focused on one change.
- Run `cargo test` and `cargo clippy` before pushing.
- Reference the issue or spec in the PR description.

## Project layout

```
src/
  cli.rs              # Clap derive structs - the CLI surface
  main.rs             # Top-level command dispatch
  api/                # Discourse HTTP client + response models
  commands/           # One module per top-level command
  config.rs           # dsc.toml resolution + parsing
docs/                 # User-facing per-command docs
spec/                 # Design specs (one per new surface)
tests/                # Integration tests (one file per command)
s/                    # Project scripts: install, test, version++, release
.marcus/              # Author-private notes (gitignored)
```

## Support stance

`dsc` is best-effort, community-driven, no SLA. Issues are triaged when the author has time; field-driven specs (see [spec/from-the-field.md](spec/from-the-field.md)) are prioritised over speculative ones because their use case is verified. If you need a guarantee, hire a contractor - the code is MIT-licensed.

## License

By contributing you agree your contribution is licensed under the same terms as the rest of the project ([MIT](LICENSE)).
