Skip to content

Commit 630fb06

Browse files
author
epriestley
committed
Document how to use harbormaster.sendmessage to report lint and unit results
Summary: Fixes T7419. This doesn't really do anything, just adds documentation. Test Plan: - Read the documentation: {F688899} - Created a build plan which makes an HTTP request to `example.com` and waits for a result. - Ran that build plan manually. - Called `harbormaster.sendmessage` manually with the example lint/unit values to provide a result. - Saw the results report correctly and the message ("fail") process as expected: {F688902} Reviewers: chad Reviewed By: chad Maniphest Tasks: T7419 Differential Revision: https://secure.phabricator.com/D13789
1 parent f0e7c65 commit 630fb06

File tree

8 files changed

+364
-29
lines changed

8 files changed

+364
-29
lines changed

‎src/__phutil_library_map__.php‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -990,6 +990,7 @@
990990
'HarbormasterManagementBuildWorkflow' => 'applications/harbormaster/management/HarbormasterManagementBuildWorkflow.php',
991991
'HarbormasterManagementUpdateWorkflow' => 'applications/harbormaster/management/HarbormasterManagementUpdateWorkflow.php',
992992
'HarbormasterManagementWorkflow' => 'applications/harbormaster/management/HarbormasterManagementWorkflow.php',
993+
'HarbormasterMessageType' => 'applications/harbormaster/engine/HarbormasterMessageType.php',
993994
'HarbormasterObject' => 'applications/harbormaster/storage/HarbormasterObject.php',
994995
'HarbormasterPlanController' => 'applications/harbormaster/controller/HarbormasterPlanController.php',
995996
'HarbormasterPlanDisableController' => 'applications/harbormaster/controller/HarbormasterPlanDisableController.php',
@@ -4702,6 +4703,7 @@
47024703
'HarbormasterManagementBuildWorkflow' => 'HarbormasterManagementWorkflow',
47034704
'HarbormasterManagementUpdateWorkflow' => 'HarbormasterManagementWorkflow',
47044705
'HarbormasterManagementWorkflow' => 'PhabricatorManagementWorkflow',
4706+
'HarbormasterMessageType' => 'Phobject',
47054707
'HarbormasterObject' => 'HarbormasterDAO',
47064708
'HarbormasterPlanController' => 'HarbormasterController',
47074709
'HarbormasterPlanDisableController' => 'HarbormasterPlanController',

‎src/applications/conduit/method/ConduitAPIMethod.php‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,41 @@
11
<?php
22

33
/**
4-
* @task status Method Status
5-
* @task pager Paging Results
4+
* @task info Method Information
5+
* @task status Method Status
6+
* @task pager Paging Results
67
*/
78
abstract class ConduitAPIMethod
89
extends Phobject
910
implements PhabricatorPolicyInterface {
1011

12+
1113
const METHOD_STATUS_STABLE = 'stable';
1214
const METHOD_STATUS_UNSTABLE = 'unstable';
1315
const METHOD_STATUS_DEPRECATED = 'deprecated';
1416

17+
18+
/**
19+
* Get a short, human-readable text summary of the method.
20+
*
21+
* @return string Short summary of method.
22+
* @task info
23+
*/
24+
public function getMethodSummary() {
25+
return $this->getMethodDescription();
26+
}
27+
28+
29+
/**
30+
* Get a detailed description of the method.
31+
*
32+
* This method should return remarkup.
33+
*
34+
* @return string Detailed description of the method.
35+
* @task info
36+
*/
1537
abstract public function getMethodDescription();
38+
1639
abstract protected function defineParamTypes();
1740
abstract protected function defineReturnType();
1841

‎src/applications/conduit/query/PhabricatorConduitSearchEngine.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ protected function renderResultList(
174174
$item = id(new PHUIObjectItemView())
175175
->setHeader($method_name)
176176
->setHref($this->getApplicationURI('method/'.$method_name.'/'))
177-
->addAttribute($method->getMethodDescription());
177+
->addAttribute($method->getMethodSummary());
178178

179179
switch ($method->getMethodStatus()) {
180180
case ConduitAPIMethod::METHOD_STATUS_STABLE:

‎src/applications/harbormaster/conduit/HarbormasterSendMessageConduitAPIMethod.php‎

Lines changed: 191 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,206 @@ public function getAPIMethodName() {
77
return 'harbormaster.sendmessage';
88
}
99

10+
public function getMethodSummary() {
11+
return pht(
12+
'Send a message about the status of a build target to Harbormaster, '.
13+
'notifying the application of build results in an external system.');
14+
}
15+
1016
public function getMethodDescription() {
17+
$messages = HarbormasterMessageType::getAllMessages();
18+
19+
$head_type = pht('Constant');
20+
$head_desc = pht('Description');
21+
$head_key = pht('Key');
22+
$head_type = pht('Type');
23+
$head_name = pht('Name');
24+
25+
$rows = array();
26+
$rows[] = "| {$head_type} | {$head_desc} |";
27+
$rows[] = '|--------------|--------------|';
28+
foreach ($messages as $message) {
29+
$description = HarbormasterMessageType::getMessageDescription($message);
30+
$rows[] = "| `{$message}` | {$description} |";
31+
}
32+
$message_table = implode("\n", $rows);
33+
34+
$rows = array();
35+
$rows[] = "| {$head_key} | {$head_type} | {$head_desc} |";
36+
$rows[] = '|-------------|--------------|--------------|';
37+
$unit_spec = HarbormasterBuildUnitMessage::getParameterSpec();
38+
foreach ($unit_spec as $key => $parameter) {
39+
$type = idx($parameter, 'type');
40+
$type = str_replace('|', pht(' or '), $type);
41+
$description = idx($parameter, 'description');
42+
$rows[] = "| `{$key}` | //{$type}// | {$description} |";
43+
}
44+
$unit_table = implode("\n", $rows);
45+
46+
$rows = array();
47+
$rows[] = "| {$head_key} | {$head_name} | {$head_desc} |";
48+
$rows[] = '|-------------|--------------|--------------|';
49+
$results = ArcanistUnitTestResult::getAllResultCodes();
50+
foreach ($results as $result_code) {
51+
$name = ArcanistUnitTestResult::getResultCodeName($result_code);
52+
$description = ArcanistUnitTestResult::getResultCodeDescription(
53+
$result_code);
54+
$rows[] = "| `{$result_code}` | **{$name}** | {$description} |";
55+
}
56+
$result_table = implode("\n", $rows);
57+
58+
$rows = array();
59+
$rows[] = "| {$head_key} | {$head_type} | {$head_desc} |";
60+
$rows[] = '|-------------|--------------|--------------|';
61+
$lint_spec = HarbormasterBuildLintMessage::getParameterSpec();
62+
foreach ($lint_spec as $key => $parameter) {
63+
$type = idx($parameter, 'type');
64+
$type = str_replace('|', pht(' or '), $type);
65+
$description = idx($parameter, 'description');
66+
$rows[] = "| `{$key}` | //{$type}// | {$description} |";
67+
}
68+
$lint_table = implode("\n", $rows);
69+
70+
$rows = array();
71+
$rows[] = "| {$head_key} | {$head_name} |";
72+
$rows[] = '|-------------|--------------|';
73+
$severities = ArcanistLintSeverity::getLintSeverities();
74+
foreach ($severities as $key => $name) {
75+
$rows[] = "| `{$key}` | **{$name}** |";
76+
}
77+
$severity_table = implode("\n", $rows);
78+
79+
$valid_unit = array(
80+
array(
81+
'name' => 'PassingTest',
82+
'result' => ArcanistUnitTestResult::RESULT_PASS,
83+
),
84+
array(
85+
'name' => 'FailingTest',
86+
'result' => ArcanistUnitTestResult::RESULT_FAIL,
87+
),
88+
);
89+
90+
$valid_lint = array(
91+
array(
92+
'name' => pht('Syntax Error'),
93+
'code' => 'EXAMPLE1',
94+
'severity' => ArcanistLintSeverity::SEVERITY_ERROR,
95+
'path' => 'path/to/example.c',
96+
'line' => 17,
97+
'char' => 3,
98+
),
99+
array(
100+
'name' => pht('Not A Haiku'),
101+
'code' => 'EXAMPLE2',
102+
'severity' => ArcanistLintSeverity::SEVERITY_ERROR,
103+
'path' => 'path/to/source.cpp',
104+
'line' => 23,
105+
'char' => 1,
106+
'description' => pht(
107+
'This function definition is not a haiku.'),
108+
),
109+
);
110+
111+
$json = new PhutilJSON();
112+
$valid_unit = $json->encodeAsList($valid_unit);
113+
$valid_lint = $json->encodeAsList($valid_lint);
114+
11115
return pht(
12-
'Send a message to a build target, notifying it of results in an '.
13-
'external system.');
116+
"Send a message about the status of a build target to Harbormaster, ".
117+
"notifying the application of build results in an external system.".
118+
"\n\n".
119+
"Sending Messages\n".
120+
"================\n".
121+
"If you run external builds, you can use this method to publish build ".
122+
"results back into Harbormaster after the external system finishes work ".
123+
"or as it makes progress.".
124+
"\n\n".
125+
"The simplest way to use this method is to call it once after the ".
126+
"build finishes with a `pass` or `fail` message. This will record the ".
127+
"build result, and continue the next step in the build if the build was ".
128+
"waiting for a result.".
129+
"\n\n".
130+
"When you send a status message about a build target, you can ".
131+
"optionally include detailed `lint` or `unit` results alongside the ".
132+
"message. See below for details.".
133+
"\n\n".
134+
"If you want to report intermediate results but a build hasn't ".
135+
"completed yet, you can use the `work` message. This message doesn't ".
136+
"have any direct effects, but allows you to send additional data to ".
137+
"update the progress of the build target. The target will continue ".
138+
"waiting for a completion message, but the UI will update to show the ".
139+
"progress which has been made.".
140+
"\n\n".
141+
"Message Types\n".
142+
"=============\n".
143+
"When you send Harbormaster a message, you must include a `type`, ".
144+
"which describes the overall state of the build. For example, use ".
145+
"`pass` to tell Harbomaster that a build completed successfully.".
146+
"\n\n".
147+
"Supported message types are:".
148+
"\n\n".
149+
"%s".
150+
"\n\n".
151+
"Unit Results\n".
152+
"============\n".
153+
"You can report test results alongside a message. The simplest way to ".
154+
"do this is to report all the results alongside a `pass` or `fail` ".
155+
"message, but you can also send a `work` message to report intermediate ".
156+
"results.\n\n".
157+
"To provide unit test results, pass a list of results in the `unit` ".
158+
"parameter. Each result shoud be a dictionary with these keys:".
159+
"\n\n".
160+
"%s".
161+
"\n\n".
162+
"The `result` parameter recognizes these test results:".
163+
"\n\n".
164+
"%s".
165+
"\n\n".
166+
"This is a simple, valid value for the `unit` parameter. It reports ".
167+
"one passing test and one failing test:\n\n".
168+
"\n\n".
169+
"```lang=json\n".
170+
"%s".
171+
"```".
172+
"\n\n".
173+
"Lint Results\n".
174+
"============\n".
175+
"Like unit test results, you can report lint results alongside a ".
176+
"message. The `lint` parameter should contain results as a list of ".
177+
"dictionaries with these keys:".
178+
"\n\n".
179+
"%s".
180+
"\n\n".
181+
"The `severity` parameter recognizes these severity levels:".
182+
"\n\n".
183+
"%s".
184+
"\n\n".
185+
"This is a simple, valid value for the `lint` parameter. It reports one ".
186+
"error and one warning:".
187+
"\n\n".
188+
"```lang=json\n".
189+
"%s".
190+
"```".
191+
"\n\n",
192+
$message_table,
193+
$unit_table,
194+
$result_table,
195+
$valid_unit,
196+
$lint_table,
197+
$severity_table,
198+
$valid_lint);
14199
}
15200

16201
protected function defineParamTypes() {
17-
$type_const = $this->formatStringConstants(array('pass', 'fail'));
202+
$messages = HarbormasterMessageType::getAllMessages();
203+
$type_const = $this->formatStringConstants($messages);
18204

19205
return array(
20206
'buildTargetPHID' => 'required phid',
21-
'lint' => 'optional list<wild>',
22-
'unit' => 'optional list<wild>',
23207
'type' => 'required '.$type_const,
208+
'unit' => 'optional list<wild>',
209+
'lint' => 'optional list<wild>',
24210
);
25211
}
26212

‎src/applications/harbormaster/engine/HarbormasterBuildEngine.php‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -317,14 +317,17 @@ private function updateWaitingTargets(array $targets) {
317317
foreach ($messages as $message) {
318318
$target = $waiting_targets[$message->getBuildTargetPHID()];
319319

320-
$new_status = null;
321320
switch ($message->getType()) {
322-
case 'pass':
321+
case HarbormasterMessageType::MESSAGE_PASS:
323322
$new_status = HarbormasterBuildTarget::STATUS_PASSED;
324323
break;
325-
case 'fail':
324+
case HarbormasterMessageType::MESSAGE_FAIL:
326325
$new_status = HarbormasterBuildTarget::STATUS_FAILED;
327326
break;
327+
case HarbormasterMessageType::MESSAGE_WORK:
328+
default:
329+
$new_status = null;
330+
break;
328331
}
329332

330333
if ($new_status !== null) {

‎src/applications/harbormaster/engine/HarbormasterMessageType.php‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<?php
2+
3+
final class HarbormasterMessageType extends Phobject {
4+
5+
const MESSAGE_PASS = 'pass';
6+
const MESSAGE_FAIL = 'fail';
7+
const MESSAGE_WORK = 'work';
8+
9+
public static function getAllMessages() {
10+
return array_keys(self::getMessageSpecifications());
11+
}
12+
13+
public static function getMessageDescription($message) {
14+
$spec = self::getMessageSpecification($message);
15+
if (!$spec) {
16+
return null;
17+
}
18+
return idx($spec, 'description');
19+
}
20+
21+
private static function getMessageSpecification($message) {
22+
$specs = self::getMessageSpecifications();
23+
return idx($specs, $message);
24+
}
25+
26+
private static function getMessageSpecifications() {
27+
return array(
28+
self::MESSAGE_PASS => array(
29+
'description' => pht(
30+
'Report that the target is complete, and the target has passed.'),
31+
),
32+
self::MESSAGE_FAIL => array(
33+
'description' => pht(
34+
'Report that the target is complete, and the target has failed.'),
35+
),
36+
self::MESSAGE_WORK => array(
37+
'description' => pht(
38+
'Report that work on the target is ongoing. This message can be '.
39+
'used to report partial results during a build.'),
40+
),
41+
);
42+
}
43+
44+
}

0 commit comments

Comments
 (0)