Blame doc/usage/flags.rst

Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
.. _flags:
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Flags
Pierre-Yves Chibon 1ffce3
=====
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Pagure offers the possibility to flag pull-requests and commits. A flag
Pierre-Yves Chibon 1ffce3
is a way for a third-party tool to provide feedback on a pull-request or a
Pierre-Yves Chibon 1ffce3
commit.
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
This feedback can be as simple as the outcome of running the tests, or some
Pierre-Yves Chibon 1ffce3
lint tool, or test coverage evolution.
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Add a flag
Pierre-Yves Chibon 1ffce3
----------
Pierre-Yves Chibon 1ffce3
René Genz ec0022
Flags can be set via the API, see the ``/api/`` URL in your pagure instance
Pierre-Yves Chibon 1ffce3
or at `pagure.io/api/ <https: 0="" api="" pagure.io="">`_ and look for the endpoints</https:>
Pierre-Yves Chibon 1ffce3
with the titles: ``Flag a commit`` or ``Flag a pull-request``.
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 443742
- **uid**: the API endpoints to add flag have an optional UID argument. It
Pierre-Yves Chibon dc4c19
  is a unique identifier (of maximum 32 characters) that is unique the commit
Pierre-Yves Chibon dc4c19
  or pull-request that is being/has been flagged.
Pierre-Yves Chibon 443742
  If it is not specified by the user/tool adding the flag, it will be
Pierre-Yves Chibon 443742
  automatically generated and in either case, will be returned in the JSON
Pierre-Yves Chibon 443742
  data returned by the API endpoints. Note that this is the only time you
Pierre-Yves Chibon 443742
  would be able to retrieve this identifier if you do not specify it
Pierre-Yves Chibon 443742
  yourself.
Pierre-Yves Chibon 443742
Pierre-Yves Chibon 443742
- **status**: this field indicates the status of the task in the system
Pierre-Yves Chibon 443742
  running it. Pagure supports the following statuses:
Pierre-Yves Chibon 443742
Pierre-Yves Chibon 443742
  - ``success``: the task ended successfully.
Pierre-Yves Chibon 443742
  - ``canceled``: the task was canceled.
Pierre-Yves Chibon 443742
  - ``failure``: the task ended but failed.
Pierre-Yves Chibon 443742
  - ``error``: the task did not end at all.
Pierre-Yves Chibon 443742
  - ``pending``: the results of this task are pending.
Pierre-Yves Chibon 68aed2
    (for ``failure`` vs ``error`` think of the test system ran the tests but
Pierre-Yves Chibon 68aed2
    they failed vs the test system did not get to run the tests)
Pierre-Yves Chibon 443742
Sergio Durigan Junior 55ceba
- **percent**: this is an optional field which can be used to provide some more
Pierre-Yves Chibon 443742
  details about the outcome of the task. For example this could be used for
Pierre-Yves Chibon 443742
  test coverage, or the number of test that failed/passed.
Pierre-Yves Chibon 443742
Pierre-Yves Chibon 443742
- **username**: the name of the system running the tests. While not being
Pierre-Yves Chibon 443742
  restricted in length, a shorter name will render better in the interface.
Pierre-Yves Chibon 443742
Pierre-Yves Chibon 443742
- **comment**: a free text form not restricted in length (however, here as
Pierre-Yves Chibon 443742
  well if the comment is too long it may render off in the interface).
Pierre-Yves Chibon 443742
René Genz ec0022
- **url**: the URL the flag is linked to and where the user should be able
Pierre-Yves Chibon 443742
  to retrieve more information about the task and its outcome.
Pierre-Yves Chibon 443742
Pierre-Yves Chibon 443742
Pierre-Yves Chibon 1ffce3
.. _example_flag_commit:
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Example of two flags on a commit:
Pierre-Yves Chibon 1ffce3
---------------------------------
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
.. image:: _static/pagure_commit_flag.png
Pierre-Yves Chibon 1ffce3
        :target: ../_images/pagure_commit_flag.png
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
.. _example_flag_pr:
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
Example of two flags on a pull-request:
Pierre-Yves Chibon 1ffce3
---------------------------------------
Pierre-Yves Chibon 1ffce3
Pierre-Yves Chibon 1ffce3
.. image:: _static/pagure_flag_pr.png
Pierre-Yves Chibon 1ffce3
        :target: ../_images/pagure_flag_pr.png