mirror of
https://github.com/watchexec/watchexec.git
synced 2024-11-16 09:08:37 +01:00
91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# Contribution guidebook
|
|
|
|
|
|
This is a fairly free-form project, with low contribution traffic.
|
|
|
|
Maintainers:
|
|
|
|
- Félix Saparelli (@passcod) (active)
|
|
- Matt Green (@mattgreen) (original author, more passive now)
|
|
|
|
Currently the project is in an active development period, with the recently-overhauled "library 2.0"
|
|
backend enabling a swathe of new features that only remain to be added and then exposed.
|
|
|
|
Contributions are accepted, but review may be delayed until the above work is finished.
|
|
|
|
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:
|
|
|
|
```console
|
|
$ env RUST_LOG=watchexec=trace,info RUST_TEST_THREADS=1 RUST_NOCAPTURE=1 cargo test --test testfile -- testname
|
|
```
|
|
|
|
To use [Tokio Console](https://github.com/tokio-rs/console):
|
|
|
|
1. Add `--cfg tokio_unstable` to your `RUSTFLAGS`.
|
|
2. Run the CLI with the `dev-console` feature.
|
|
|
|
|
|
## PR etiquette
|
|
|
|
- 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!
|
|
|
|
|
|
## Releasing
|
|
|
|
A release goes through these steps:
|
|
|
|
1. Opening a draft release. Before even merging anything, a draft (only visible privately) release
|
|
is made. These are a github feature and only visible to maintainers. Name the release: which part
|
|
of the project the release is for (`CLI` or `Lib`), and the version. E.g. `CLI 1.18.0`.
|
|
|
|
2. Adding each change to the draft release. The releases pages on github serves as a changelog, so
|
|
this is worth getting right. One sentence per change, focusing on what it is, what it adds, what
|
|
it changes, if any. Add a link or PR/issue number if relevant. For example:
|
|
|
|
> - #160 :warning: Stop initialising the logger in the library code. Downstream users will need
|
|
> to initialise their own logger if they want debug/warn output.
|
|
|
|
3. Merging the PRs. Merge commits are preferred over rebase or squash.
|
|
|
|
4. Cleaning up the code and documentation if needed. For example a PR that adds a flag may not have
|
|
also added the corresponding completions, manpage entries, readme entries. Or two PRs may
|
|
conflict slightly or do the same thing twice, in which case harmonising things is required here.
|
|
|
|
5. Run `cargo fmt`, `cargo test`, `cargo clippy`, `bin/manpage`. Commit the result, if any.
|
|
CI will also run, wait for that. In the meantime:
|
|
|
|
6. Run through related issues to the PRs and close them if that wasn't done automatically. Or if the
|
|
PRs only fixed a problem partially, chime in to mention that, and to restate what remains to fix.
|
|
|
|
7. "Real" test the new code. If new options were added, test those.
|
|
|
|
8. Check for any dependency updates with `cargo outdated -R`.
|
|
|
|
9. Run `bin/cli-version 1.2.3` where `1.2.3` is the new version number. This will tag and push,
|
|
triggering the GitHub Action for releases. Use `bin/lib-version` to release a library update.
|
|
|
|
10. Wait for all builds to complete, then attach the draft release to the tag, and publish it.
|
|
|
|
11. Run the `cargo publish`.
|
|
|
|
12. Announce the release.
|
|
|
|
---
|
|
vim: tw=100
|