openSUSE:Build Service Concept Requests
Requests
The Build Service will have a general request system. From the demand of a Merge Request or Submit Request as a starting point we found out in discussions that we probably benefit from a more generic request system in the Build Service.
That makes it easier to set up general things like overview pages, reportings, notifications and workflow functionality to work with all pending requests, which should be discussed under the topic request management.
Examples for requests beside the submit request are rename requests, drop requests and user-add requests. (These do not exist yet).
The request data structure in XML will contain a general part that contains data that is common to all requests and a part with specialised information for the certain request type.
The general part contains data like lifecycle information which tracks the changes on a request.
Request datastructure
This is a short explanation of the XML based datastructure for requests.
Example: submit request
Here is an example of a request which is used to use the user asks for the submit of a patch done in a private package into an official package:
<?xml version="1.0" encoding="UTF-8"?>
<request id="4711">
<action type="submit">
<source project="home:kfreitag" package="kraft_jp" />
<target project="home:krafti" package="kraft" />
</action>
<name>Tritratrallala Patch</name>
<description>This patch fixes japanese.</description>
<state name="rejected" who="bauersman" when="2008-01-07T12:23:00">
<comment>Breaks everything except japanese</comment>
</state>
<history name="new" who="freitag" when="2008-01-05T03:51:00/>
</request>
The first part of the request contains the request specific part which is surrounded by the submit tags.
General request data
The general request data contain the elements name, description, state and history. A unique ID is added as an attribute to the root element request when the request is stored on the server.
History
The history elements represent the states the request went through. Whenever the request changes state, a new history element is added.
Every state tag contains the name of the state, a name who moved the request to the state and when.
Currenty existing states are new, deleted, declined, accepted, revoked and review.
The state has a comment tag to give a reason why the request was moved in the state, like a reject reason. It can be empty.
Request handling
Requests are mainly created through software that enables users to do things that cause requests, for example creating changes to packages they do not own. Requests are not to be created by users directly.
API call definition
Request creation
Requests are created by sending
POST /request?cmd=create
The initial request document has to be sent in the request body and must neither contain the id attribute nor history elements. On success (HTTP 200), the API responds with the request document including a generated unique id. On error, the default error xml is returned.
List requests
A single request can be accessed through a direct url with its numeric id
GET /request/<id>
The request list for both user and project are available through the search interface:
GET /search/request/<requesttype>?match
For example
GET /search/request?match=state/@name='new'%20and%20submit/target/@project='openSUSE%3ATools'
to list all requests in "new" state and are targeted to the openSUSE:Tools project.
That returns a joined collection of all requests matching to the query.
Change request status
To change the status of a request send a POST to the request url
POST /request/<id>
with the parameter cmd=changestate&newstate=<state>. The username is taken from the authentication subsystem.
To completely delete a request, the status has to be changed to deleted or a DELETE request has to be issued:
DELETE /request/<id>
Modify request
To modify properties of a request (e.g. description), issue a PUT request:
PUT /request/<id>
The request document has to be sent in the HTTP request body; id attribute and history elements will be ignored and set to proper values.