openSUSE:Build Service Concept AttributeStorage
If you want to contribute, please read the rules for this wiki and if you have any questions, don't hesitate to contact the wiki team, we are more then willing to help you! :-)
NOTE: This is almost implemented and running at the opensuse.org instance. However, the interfaces and the system might still change until 1.7 release!
The attribute system of OBS is designed to allow to store simple informations to a package or project. An attribute needs to be specified first to allow it's usage. The attribute definition are organized within namespaces.
Possible usages of attributes are any kind of meta informations, like:
- Package maintenance status
- Links to external resources, for example bugreports or screenshots
- References to update resources
Any attribute can be used also as a marker for efficient searches. For example, give me all package sources called "glibc" which shall be updated on security updates.
The status of this concept is WIP, it is half implemented in svn, but not yet deployed on the server.
Everything might change until final 1.7, but candidates are esp:
- move namespace and attribute type definition out of project _meta file.
- Current limitation that admin rights are required for attribute definitions in any case will go away.
Attribute definition
A namespace and/or attribute must be specified in a project meta file. This looks like this:
<project ...
...
<attributes>
<namespace name="OBS">
<modifiable_by group="Admin"/>
</namespace>
<definition name="maintained" namespace="OBS">
<default>
<value>no</value>
<value>0</value>
</default>
<allowed>
<value>0</value>
<value>no</value>
<value>security_only</value>
<value>full_maintenance</value>
</allowed>
<count>2</count> <! -- this attribute must always contain two values -->
<modifiable_by user="demouser"/>
<modifiable_by group="demogroup"/>
<modifiable_by role="demorole"/>
</definition>
</attributes>
...
</project>
The namespace is only to be allowed to be defined at one place. To create a new namespace you will need admin rights.
The modifiable_by permissions inside of a namespace element specify who will be allowed to modify the attribute definitions inside of this namespace. "OBS" will be reserved namespace, which shall only be touched by the OBS developers, because shipped tools and the system relies on it.
The definition element is defining one attribute. All elements inside of it are optional.
To view the namespace OBS, you can use:
osc meta prj OBS
Setting attributes
Attributes are stored in an own file of a package or project. They can be reached via
/source/<project>/<package>/_attribute
A "GET" operation lists all attributes for a project or package, this can look like this
<attributes>
<attribute name="OBS:maintained" />
<attribute name="OBS:maintained" binarypackage="blah-devel" />
<attribute name="OBS:bugnumbers">
<value>12345</value>
<value>0815</value>
</attribute>
</attributes>
A "POST" operation is used for modifying or creating the send attributes and a "DELETE" is for removing them again.
The API
Read and set attributes
The attributes are part of the package meta files and can be modified via them. However, to avoid to download and parse the entire meta file for just reading one attribute there will be a attribute api call.
It will also allow to modify attributes, even without write permissions to the meta file, if this is allowed in attribute type definition.
GET /source/$PROJECT/_attribute[/$ATTRIBUTE_NAME]?with_default=1 GET /source/$PROJECT/$PACKAGE/_attribute[/$ATTRIBUTE_NAME]?with_default=1&with_project=1
POST /source/$PROJECT/_attribute POST /source/$PROJECT/$PACKAGE/_attribute
DELETE /source/$PROJECT/_attribute[/$ATTRIBUTE_NAME] DELETE /source/$PROJECT/$PACKAGE/_attribute[/$ATTRIBUTE_NAME]
The leading $ATTRIBUTE_NAME is optional for GET and DELETE operations. If not set all attributes are affected. Please note that this only affects the attribute values, but not the definition or namespace declaration in project case.
The with_defaults parameter is allowed on GET operations to give the default value, if no other value is defined. with_project_value works similar, but is falling back to the project attribute value.
Search by attributes
OBS allows you to search for all packages or projects which provide a certain attribute or even bound to be set to a certain value via standard search/XPath interface:
GET /search/package?match=[attribute/@name="OBS:maintained"]
The result is a collection as usual:
<collection>
<package project="openSUSE:11.2" name="libtheora">
<attributes....
....
</attributes>
</package>
<package ....
...
</package>
</collection>
Please note that it matches for a package independent if the attribute is set in the package or in the project.
OSC integration
This blog describes how to use the attributes with osc.
Example definition as it might be used on openSUSE.org server
This is just a collection, based on ideas when talking to people:
<attributes>
<namespace name="OBS"> <! -- exists in all OBS instances -->
<modifiable_by role="Admin"/>
</namespace>
<namespace name="openSUSE"> <! -- exists only in opensuse.org OBS -->
<modifiable_by group="Admin"/>
</namespace>
<! -- OBS global attributes -->
<definition name="Maintained" namespace="OBS" >
<count>0</count>
<modifiable_by role="Admin"/>
</definition>
<definition name="UpdateProject" namespace="OBS" >
<count>1</count>
<modifiable_by role="Admin"/>
</definition>
<definition name="Screenshots" namespace="OBS" > <! -- unlimited number of values(URLs) -->
<modifiable_by role="maintainer"/>
</definition>
<! -- openSUSE attributes -->
<definition name="L3-Support" namespace="openSUSE" >
<allowed>
<value>no</value>
<value>upstream_only</value>
<value>security_only</value>
<value>full_maintenance</value>
</allowed>
<count>1<count>
<modifiable_by role="bugowner"/>
</definition>
</attributes>