From 66555c9b183a0248c9d6d9866b24ea9929d7de48 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fe=CC=81lix=20Saparelli?= <felix@passcod.name>
Date: Fri, 3 Jul 2020 23:51:46 +1200
Subject: [PATCH] Add CONTRIBUTING.md

---
 CONTRIBUTING.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3c86dca
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,99 @@
+# 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