docs: Add X-Patchwork-* header documentation

Avoids sending people to the code to find out about this stuff. Include
examples using 'git-send-email', which should cover most folks.

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/TODO b/docs/TODO
index 17d8cd17a70796a7fa57931fa3a6aed830af831c..37c30fd951dd0743e56faefa70eeb3bc376c016e 100644 (file)
--- a/docs/TODO
+++ b/docs/TODO
@@ -2,7 +2,7 @@
 * Person link should go to -> (person,project) patch list view
 * https for logins
 * Patch flags
-* Help: XML RPC interface, bundling, Hint headers
+* Help: bundling
 * Allow manual update of commit ref
 * store rejected mails
 * In-message From: header

diff --git a/docs/usage/headers.md b/docs/usage/headers.md
new file mode 100644 (file)
index 0000000..dc87397
--- /dev/null
+++ b/docs/usage/headers.md
@@ -0,0 +1,34 @@
+# Hint Headers
+
+Patchwork provides a number of special email headers to control how a patch is
+handled when it is received. The examples provided below use `git-send-email`,
+but custom headers can also be set when using tools like `mutt`.
+
+## `X-Patchwork-Ignore`
+
+Valid values: *
+
+When set, the mere presence of this header will ensure the provided email is
+not parsed by Patchwork. For example:
+
+    $ git send-email --add-header="X-Patchwork-Ignore: test" master
+
+## `X-Patchwork-Delegate`
+
+Valid values: An email address associated with a Patchwork user
+
+If set and valid, the user corresponding to the provided email address will be
+assigned as the delegate of any patch parsed. If invalid, it will be ignored.
+For example:
+
+    $ git send-email --add-header="X-Patchwork-Delegate: a@example.com" master
+
+## `X-Patchwork-State`
+
+Valid values: Varies between deployments. This can usually be one of
+"Accepted", "Rejected", "RFC" or "Awaiting Upstream", among others.
+
+If set and valid, the state provided will be assigned as the state of any patch
+parsed. If invalid, it will be ignored. For example:
+
+    $ git send-email --add-header="X-Patchwork-State: RFC" master

diff --git a/mkdocs.yml b/mkdocs.yml
index 0332f461a9c1f11e6f9f7e67fb88e149924dfdeb..ceb57d93aee150197720a9afaad7a8dceb86f959 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -17,3 +17,4 @@ pages:
  - Usage Guide:
    - REST API: 'usage/rest.md'
    - XML-RPC API: 'usage/xmlrpc.md'
+   - Hint Headers: 'usage/headers.md'