watchexec/CONTRIBUTING.md

# Contribution guidebook


This is a fairly free-form project, with low contribution traffic. It is mostly passively
maintained, with occasional bouts of more active developing, usually along a theme. Most of the
maintainer activity is triaging and managing issues, and loosely planning/grouping feature requests
and non-critical bugs to fix into these themes, represented as milestones.

Maintainers:

- Félix Saparelli (@passcod) (active)
- Matt Green (@mattgreen) (original author, more passive now)

Currently the project is in a long v1 phase, with a "sometime in the future" second phase, which at
the moment I envision as something with a stronger semver focus, and a major version number that may
increase more often. Possibly the project would be split in two or more crates, to facilitate this.

So, semver. Watchexec remains semver-compatible... on the CLI interface only. The library interface
is explicitly _not_ considered as part of breaking changes, and even _patch_ version number changes
may actually involve API breakage at the library interface.

Additionally, it is to be considered unwise to rely on the _output_ of the CLI as an interface. The
semver aspects are fairly loose but focus on input (flags, options, arguments, env), behaviour, and
the calling environment of the sub process.

Contributions are accepted for literally everything. 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.


## 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:

0. Versioning indications on PRs. These are statements by the maintainers when reviewing or
   discussing PRs generally in `[square brackets]` that make an indication of what implication
   merging the PR will have on versioning. For example:

   > [versioning note: this is a feature add but not considered an api breaking change (due to the builder)]

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... that can
   be descriptive or whimsical or both. Release title template is `{version without v}: {title}`.

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`. 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. Change the version number, run `cargo check`, and make a commit that contains _only_ the
   Cargo.toml and Cargo.lock changes. Use the version number (without `v` prefix) as only message.

9. Create an annotated tag named the naked version (without `v` prefix), with identical message:

   ```
   $ git tag -am 1.14.0{,}
   ```

10. Push: `$ git push --follow-tags`.

11. Edit the draft release, select the newly pushed tag, and publish it. Built artifacts will get
    built and get added automatically to the release as downloads.

12. Run the `cargo publish`.

13. Announce the release.

---
vim: tw=100