From 4437424d1d68c0cd5661f9cc99a3f52fd68f2cf0 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Nov 22 2017 16:45:23 +0000 Subject: Expand the documentation about flags Signed-off-by: Pierre-Yves Chibon --- diff --git a/doc/usage/flags.rst b/doc/usage/flags.rst index 10e3b30..8304706 100644 --- a/doc/usage/flags.rst +++ b/doc/usage/flags.rst @@ -20,6 +20,40 @@ or at `pagure.io/api/ `_ and look for the endpoints with the titles: ``Flag a commit`` or ``Flag a pull-request``. +- **uid**: the API endpoints to add flag have an optional UID argument. It + is a unique identifier (of maximum 32 characters) that is unique for the + entire pagure instance and allows to edit a flag. + If it is not specified by the user/tool adding the flag, it will be + automatically generated and in either case, will be returned in the JSON + data returned by the API endpoints. Note that this is the only time you + would be able to retrieve this identifier if you do not specify it + yourself. + +- **status**: this field indicates the status of the task in the system + running it. Pagure supports the following statuses: + + - ``success``: the task ended successfully. + - ``canceled``: the task was canceled. + - ``failure``: the task ended but failed. + - ``error``: the task did not end at all. + - ``pending``: the results of this task are pending. + (for ``failure`` vs ``error`` think of the test system ran the tests but + they failed vs the test system did not get to run the tests) + +- **percent**: this is an optional field which allows to provide some more + details about the outcome of the task. For example this could be used for + test coverage, or the number of test that failed/passed. + +- **username**: the name of the system running the tests. While not being + restricted in length, a shorter name will render better in the interface. + +- **comment**: a free text form not restricted in length (however, here as + well if the comment is too long it may render off in the interface). + +- **url**: the url the flag is linked to and where the user should be able + to retrieve more information about the task and its outcome. + + .. _example_flag_commit: Example of two flags on a commit: