Contribution guidebook

This is a fairly free-form project, with low contribution traffic.

Maintainers:

There are a few anti goals:

Calling watchexec is to be a simple exercise that remains intuitive. As a specific point, it should not involve any piping or require xargs.
Watchexec will not be tied to any particular ecosystem or language. Projects that themselves use watchexec (the library) can be focused on a particular domain (for example Cargo Watch for Rust), but watchexec itself will remain generic, usable for any purpose.

Debugging

To enable verbose logging in tests, run with:

$ env RUST_LOG=watchexec=trace,info RUST_TEST_THREADS=1 RUST_NOCAPTURE=1 cargo test --test testfile -- testname

Maintainers are busy or may not have the bandwidth, be patient.
Do not change the version number in the PR.
Do not change Cargo.toml or other project metadata, unless specifically asked for, or if that's the point of the PR (like adding a crates.io category).

Apart from that, welcome and thank you for your time!

cargo release -p crate-name --execute patch # or minor, major

When a CLI release is done, the release notes should be edited with the changelog.

Use this command to see the tree of workspace dependencies:

$ cargo tree -p watchexec-cli | rg -F '(/' --color=never | sed 's/ v[0-9].*//'

The architecture of watchexec is roughly:

sources gather events
events are debounced and filtered
event(s) make it through the debounce/filters and trigger an "action"
on_action handler is called, returning an Outcome
outcome is processed into managing the command that watchexec is running
- outcome can also be to exit
when a command is started, the on_pre_spawn and on_post_spawn handlers are called
commands are also a source of events, so e.g. "command has finished" is handled by on_action

And this is the startup sequence:

init config sets basic immutable facts about the runtime
runtime starts:
- source workers start, and are passed their runtime config
- action worker starts, and is passed its runtime config
(unless --postpone is given) a synthetic event is injected to kickstart things

These are generic guides for implementing specific bits of functionality.

add a worker for "sourcing" events. Looking at the signal source worker is probably easiest to get started here.
because we may not always want to enable this event source, and just to be flexible, add runtime config for the source.
for convenience, probably add a method on the runtime config which configures the most common usecase.
because watchexec is reconfigurable, in the worker you'll need to react to config changes. Look at how the fs worker does it for reference.
you may need to add to the event tag enum.
if you do, you should add support to the "tagged filterer", but this can be done in follow-up work.

vim: tw=100