28 Request and Review System #
The OBS comes with a generic request system where one party can ask another to complete a certain action. This can be, for example, taking source changes, granting maintainer rights or deleting a package. Requests are also used deal with more complex workflows.
A request is an object in the database. It can be accessed via the /request API route. osc and the web interface can show and process these requests. There are also interfaces to show the requests which should be handled for a certain user.
28.1 What a request looks like #
A request is an object in the database. It can be accessed via the /request API route. Main parts of the request are
state: The state tells if the request still needs to processed or has been handled already and how.
actions: these are the changes which will be applied when accepting the request.
reviewer: reviewer can be added automatically at request creation time or manually by any involved party. Usually all of them should approve the request before it will be accepted. However, the target can ignore that and accept anyway optionally.
description: an explanation of why the actions should be done.
history: a history about state changes of the request.
accept_at: the request will get accepted automatically after the given time. Such a request can only be created when having write permissions in the target. Automatic cleanup requests created by Admin user are using this.
Requests can only be accepted or rejected in their entirety. Therefore, it can make sense to have multiple actions in one request if changes should be applied in one transaction. For example, submitting a new package and removing an old instance: Do either both or nothing. This implies that the person accepting the request must have write access in all targets or they will not be allowed to accept the request.
28.1.1 Action Types #
Actions always specify some target. This can be either a project or a package. Further information depend on the action type. The following gives an overview, for details, see the XML schema for requests.
28.1.1.1 submit #
A submit action will transfer sources from one package to another
package. Usually a submit request will refer to a specific revision in the
source, but it does not have to. If no revision is specified, then the
current revision at the time of acceptance will be used. This should be
avoided when relying on complex reviews during the request process. Hence,
it is recommended to identify a specific version in your submitrequest
(osc submitrequest -r 42 ...).
The submit action can support options to update the source or even to remove the source. Tools like osc are applying the cleanup rule by default when submitting from a default user home branch project.
28.1.1.2 release #
Is used to release a finished build. Sources and binaries are copied
without a rebuild (The target project should have build disabled). A release
target needs to be defined with
trigger="manual".
28.1.1.3 delete #
A delete action can request removal of a project or package instance.
28.1.1.4 add_role #
An add_role requests a specific role for a given user or group to the target. For example, one could use this to ask for maintainer rights, or to become a default reviewer.
28.1.1.5 set_bugowner #
set_bugowner is similar to add_role, but removes all other bugowner roles in the target. This happens to have a unique identifier to be used when assigning bug reports in external tools like Bugzilla.
28.1.1.6 change_devel #
can be used to update the devel package information in the target.
28.1.1.7 maintenance_incident #
Official request to open a maintenance incident for official support products. These requests are created by developers who want to start an official maintenance process. Details are described in the maintenance chapter. A new maintenance incident project is created and package sources get copied there when accepting it. All sources of all actions in one request will be merged into the same maintenance incident project.
28.1.1.8 maintenance_release #
Is used to release a maintenance update. Sources and binaries are copied without a rebuild. Open Build Service also creates a unique update identifier. Details can be found in the maintenance chapter.
28.1.1.9 group #
Deprecated. Was never in a released OBS version. It is not allowed to be used anymore.
28.1.2 Request states #
new: The default value for newly created requests. Everybody involved in the specified targets can see the request and accept or decline it.
accepted: The request has been accepted and the changes applied. history files have a reference to this request.
declined: The request has been reviewed and not (yet) been accepted by the target. This is often used to ask for some more information from the submitter, since declined requests remain active, returning to the submitter's active request queue (that is, the submitter will need to take action now).
revoked: The submitter has taken back their request. The request is considered to be inactive now.
superseded: This request is obsolete due to a new request. The request is considered to be inactive now. The superseding request is linked in this request.
review: There are still open reviews inside of the request. Nobody has declined it yet. The request is not yet visible to the target by default. The state will change automatically to new when all reviewers accept.
28.1.3 Reviewers #
Reviews can be done by users, groups, projects or packages. Review by project or package means that any maintainer of them is asked for reviews. This is handy to avoid the need to figure who actually is a maintainer of a certain package. Also, new maintainers of a package will see requests in case the old maintainer did not handle them.
28.1.3.1 Manually added reviews #
Reviewers can be added manually by anyone involved in a request. This can be used to hand over a review. In that situation the new reviewer needs to be added and the original reviewer's own review needs to be accepted. The request becomes declined when any of the reviewers are declining the request.
28.1.3.2 Automatically added reviews #
Project and package objects can have users or groups with a reviewer role. They are added automatically to a request as reviewer when a request is created which has them as target. In case the project and package do specify reviewers, all of them are added to the request.
28.1.4 Request creation #
The API is doing a number of checks at request creation time. In case a target is not specified it tries to set it according to the linked package. If an entire project is specified as source it expands it to all packages inside. This means it is replacing one action with multiple. When using the addrevision parameter it does also add the current revision of the package source to the action. This makes it easy to create new requests with little logic in the client.
28.1.5 Request operations #
Requests can be modified only in very limited ways after creation. This is to avoid the nature of the request changing, after reviewers have reviewed it. Valid operations on a request are:
diff: does not modify the request, just shows source modifications wanted by the request
changestate: to change the state of the request, for example to accept it.
changereviewstate: to change the state of a review inside of a request.
addreviewer: add further reviewer to a request
28.2 Who can accept a request #
The question of who can accept a request can be answered by inspecting who has write permissions on the target project of the request. This includes both maintainers listed in the project itself, plus all maintainers of higher-level projects within the project hierarchy. (For example, requests touching a project "foo:bar" can be accepted by all maintainers of that project, as well as by all maintainers of the project "foo".)