From 5b8577db59d324ca09764be70540d8ae63da901b Mon Sep 17 00:00:00 2001
From: jungejason <jun.ge.jason@fb.com>
Date: Fri, 10 Feb 2012 10:14:12 -0800
Subject: [PATCH] Add documentation for the Owners tool

Summary:
As title.

Please help me to improve the wording!

Test Plan:
generate the documentation from the diviner file; read it; spell
check

Reviewers: epriestley, nh

Reviewed By: nh

CC: aran, dihde14, mpodobnik, prithvi, TomL, epriestley

Differential Revision: https://secure.phabricator.com/D1395
---
 .../base/PhabricatorOwnersController.php      | 10 +++++++
 .../owners/controller/base/__init__.php       |  1 +
 .../edit/PhabricatorOwnersEditController.php  |  4 +++
 src/docs/userguide/owners.diviner             | 30 +++++++++++++++++++
 4 files changed, 45 insertions(+)
 create mode 100644 src/docs/userguide/owners.diviner

diff --git a/src/applications/owners/controller/base/PhabricatorOwnersController.php b/src/applications/owners/controller/base/PhabricatorOwnersController.php
index 28e6380a9c..8202a1dc78 100644
--- a/src/applications/owners/controller/base/PhabricatorOwnersController.php
+++ b/src/applications/owners/controller/base/PhabricatorOwnersController.php
@@ -39,6 +39,16 @@ abstract class PhabricatorOwnersController extends PhabricatorController {
     $nav->appendChild($view);
     $page->appendChild($nav);
 
+    $doclink =
+      PhabricatorEnv::getDoclink('article/Owners_Tool_User_Guide.html');
+    $tabs = array(
+      'help' => array(
+        'href' => $doclink,
+        'name' => 'Help',
+      ),
+    );
+    $page->setTabs($tabs, null);
+
     $response = new AphrontWebpageResponse();
     return $response->setContent($page->render());
   }
diff --git a/src/applications/owners/controller/base/__init__.php b/src/applications/owners/controller/base/__init__.php
index 07c823a477..db31e61848 100644
--- a/src/applications/owners/controller/base/__init__.php
+++ b/src/applications/owners/controller/base/__init__.php
@@ -8,6 +8,7 @@
 
 phutil_require_module('phabricator', 'aphront/response/webpage');
 phutil_require_module('phabricator', 'applications/base/controller/base');
+phutil_require_module('phabricator', 'infrastructure/env');
 phutil_require_module('phabricator', 'view/layout/sidenavfilter');
 
 phutil_require_module('phutil', 'parser/uri');
diff --git a/src/applications/owners/controller/edit/PhabricatorOwnersEditController.php b/src/applications/owners/controller/edit/PhabricatorOwnersEditController.php
index 7a1ba89c2c..9f6d487a8b 100644
--- a/src/applications/owners/controller/edit/PhabricatorOwnersEditController.php
+++ b/src/applications/owners/controller/edit/PhabricatorOwnersEditController.php
@@ -219,6 +219,10 @@ class PhabricatorOwnersEditController extends PhabricatorOwnersController {
         id(new AphrontFormSelectControl())
           ->setName('auditing')
           ->setLabel('Auditing')
+          ->setCaption('With auditing enabled, all future commits that touch '.
+                       'this package will be reviewed to make sure an owner '.
+                       'of the package is involved and the commit message has '.
+                       'a valid revision, reviewed by, and author.')
           ->setOptions(array(
             'disabled'  => 'Disabled',
             'enabled'   => 'Enabled',
diff --git a/src/docs/userguide/owners.diviner b/src/docs/userguide/owners.diviner
new file mode 100644
index 0000000000..23238ae943
--- /dev/null
+++ b/src/docs/userguide/owners.diviner
@@ -0,0 +1,30 @@
+@title Owners Tool User Guide
+@group userguide
+
+Use Owners to define and/or monitor code you care about.
+
+= Packages =
+
+Owners tool allows you to define a code package by specifying a group of paths.
+The package can then be used to monitor the paths. For example, it can be used
+in Herald rules and in the "Related Commits" feature (see below).
+
+= Related Commits =
+
+Once the package is defined, all future commits touching any path defined in
+the package will be recorded as "Related Commits" of the package.
+
+= Commits Needing Attention =
+
+Owners tool enables the owners of the package to monitor the commits that might
+need attention. If "auditing" is enabled for a package, a related commit will
+be marked as "Needing Attention" if
+
+  - it's neither authored nor reviewed by an owner of the package,
+  - no revision found for the commit,
+  - the commit author is not recognized, or
+  - the author or the reviewer specified in the commits don't match the ones in
+  the Differential revision
+
+The owners of the package can accept or specify concern for such commits by
+clicking the "Audit Status" link.