# Contributing to fledge
Thanks for your interest in contributing to fledge! Whether it's a bug fix, new feature, documentation improvement, or template — contributions are welcome.
## Getting Started
### Prerequisites
- [Rust](https://rustup.rs/) (stable toolchain)
- Git
- A GitHub account (for PRs and issue tracking)
### Clone and Build
```bash
git clone https://github.com/CorvidLabs/fledge.git
cd fledge
cargo build
cargo test
```
### Run from Source
```bash
cargo run -- init my-test --template rust-cli
cargo run -- run test
```
## Development Workflow
### 1. Find or Create an Issue
Check [existing issues](https://github.com/CorvidLabs/fledge/issues) first. If your change is non-trivial, open an issue to discuss the approach before writing code.
### 2. Create a Branch
```bash
# Use fledge itself for branch management
cargo run -- work start my-feature
# Or manually
git checkout -b feat/my-feature
```
Branch naming convention: `{type}/{description}` where type is `feat`, `fix`, `chore`, `docs`, `refactor`, or `hotfix`.
### 3. Make Your Changes
- Read the relevant spec in `specs/` before modifying a module
- Follow the existing code style (Rust idioms, `anyhow` for errors)
- Add tests for new functionality
- Update documentation if you change CLI behavior
### 4. Verify
```bash
cargo build # compiles
cargo test # all tests pass
cargo clippy -- -D warnings # no lint warnings
cargo fmt --check # formatting is correct
cargo run -- spec check # specs are in sync
```
All four checks must pass before submitting a PR.
### 5. Submit a Pull Request
```bash
# Use fledge
cargo run -- work pr --title "Add my feature"
# Or use gh/GitHub
```
In your PR description:
- Explain **what** changed and **why**
- Reference any related issues (`Fixes #123`)
- Note any breaking changes
## What to Contribute
### Good First Issues
Look for issues labeled [`good first issue`](https://github.com/CorvidLabs/fledge/labels/good%20first%20issue). These are scoped, well-defined tasks suitable for newcomers.
### Templates
Create new templates and publish them with `fledge publish`. See the [Template Authoring Guide](https://corvidlabs.github.io/fledge/template-authoring.html) for the full format.
### Plugins
Build plugins that extend fledge with new commands. See the [Plugins Guide](https://corvidlabs.github.io/fledge/plugins.html) for the plugin format.
### Lanes
Share workflow pipelines via the community lane registry. Push a repo with a `fledge.toml` and add the `fledge-lane` topic.
### Documentation
Documentation lives in `docs/src/` and is built with [mdBook](https://rust-lang.github.io/mdBook/). To preview locally:
```bash
# Install mdBook if you don't have it
cargo install mdbook
# Serve locally
cd docs && mdbook serve
```
## Code Guidelines
### Architecture
- Each CLI command lives in its own module (`src/<command>.rs`)
- `src/main.rs` handles argument parsing and dispatch
- Shared GitHub helpers are in `src/github.rs`
- Specs in `specs/` define how each module should work — read them before modifying code
### Error Handling
- Use `anyhow::Result` for all public functions
- Use `anyhow::bail!` for early returns with error messages
- Error messages should be user-friendly and actionable
### Testing
- Unit tests go in `#[cfg(test)] mod tests` at the bottom of each module
- Integration tests go in `tests/`
- Test both the happy path and error cases
- Use `tempfile` for tests that write to disk
### Style
- Run `cargo fmt` before committing
- Run `cargo clippy -- -D warnings` and fix all warnings
- No `unsafe` code without discussion
- Prefer standard library types over external crates when practical
## Specs
Every module has a spec in `specs/<module>/`. The spec is the source of truth for what the module does. Before modifying a module:
1. Read its spec
2. If your change alters behavior, update the spec first
3. Run `cargo run -- spec check` to verify alignment
## Release Process
Releases are handled by maintainers. The process:
1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md` with new entries
3. Tag with `git tag v<version>`
4. Push tag — CI builds and publishes to crates.io, Homebrew, and GitHub Releases
## Code of Conduct
Be respectful and constructive. We're building tools, not arguments. Harassment, discrimination, and unconstructive behavior aren't tolerated.
## License
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).