How to contribute

This section captures everything you need to know to land a change in fd. The authoritative document is CONTRIBUTING.md; this page summarises it and pairs it with a guide to the codebase's actual structure.

Picking up work

• Look at open issues for good first issue and help wanted labels.
• For non-trivial features, open an issue first. The maintainers explicitly ask for this in CONTRIBUTING.md to avoid wasted PRs.
• If you have an idea that isn't filed yet, file an issue with a clear motivation and a proposed UX.

PR expectations

The expectations spelled out in CONTRIBUTING.md (PR #1967, April 2026):

1. Submit best-effort, self-reviewed code. PRs from generative AI are allowed only if you have reviewed them, understand them, and can defend and modify them.
2. Make sure the build passes locally before opening the PR. CI may fail on one or two specific targets; that's tolerable, but a PR that fails to compile anywhere is not.
3. You are responsible for ensuring your contribution does not violate copyrights or patents — particularly relevant if an LLM produced look-alike code.
4. Disclose AI tool usage in the PR description if you used one, and indicate the extent.

Updating the changelog

Any change that affects user-visible behaviour must come with a CHANGELOG.md entry. The top of the file has an "Unreleased" section split into Features, Bugfixes, and Changes. Add a bullet in this format:

- Short description of what has been changed, see #123 (@user)

Pure documentation typo fixes can skip the changelog.

Definition of done

Before pushing the branch:

cargo fmt -- --check                           # rustfmt clean
cargo clippy --all-targets --all-features -- -Dwarnings   # no clippy warnings
cargo test --all-features                      # tests pass

CI runs the same three commands plus an MSRV build of Rust 1.90.0 with --all-features. See .github/workflows/CICD.yml.

Working in this codebase

You want to …	Read this page
understand the file layout and lifecycle of a search	overview/architecture
add or change a CLI flag	systems/cli-parsing
change how directories are walked, filtered, or buffered	systems/walker
add a new filter (size, time, ownership, …)	systems/filters
change --exec/--exec-batch or the --format template	systems/command-execution and systems/format-templates
change how matches are printed	systems/output
understand how .gitignore/.fdignore are honoured	systems/ignore-rules
run the test suite or write new integration tests	how-to-contribute/testing
reproduce a build issue locally	how-to-contribute/development-workflow
debug a hang, panic, or weird traversal	how-to-contribute/debugging
understand recurring code patterns	how-to-contribute/patterns-and-conventions
see what tooling lives in the repo	how-to-contribute/tooling

License and security

• fd is dual-licensed under MIT or Apache-2.0. Both license texts ship in the repo. Contributions are accepted under the same dual license.
• Security issues should be reported via the GitHub Security Advisory form linked from SECURITY.md. Do not open public issues for vulnerabilities.