About this Guide #

This guide is part of the Open Build Service documentation. These books are considered to contain only reviewed content, establishing the reference documentation of OBS.

This guide does not focus on a specific OBS version. It is also not a replacement of the documentation inside of the openSUSE Wiki. However, content from the wiki may be included in these books in a consolidated form.

1 Available Documentation #

The following documentation is available for OBS:

Book “Administrator Guide”: This guide offers information about the initial setup and maintenance for running Open Build Service instances.
Book “User Guide”: This guide is intended for users of Open Build Service. The first part describes basic workflows for working with packages on Open Build Service. This includes checking out a package from an upstream project, creating patches, branching a repository, and more. The following parts go into more detail and contain information on backgrounds, setting up your computer for working with OBS, and usage scenarios. The Best Practices part offers step-by-step instructions for the most common features of the Open Build Service and the openSUSE Build Service. The last part covers ideas and motivations, concepts and processes of the Open Build Service.

2 Feedback #

Several feedback channels are available:

Bugs and Enhancement Requests: Help for openSUSE is provided by the community. Refer to https://en.opensuse.org/Portal:Support for more information.
Bug Reports: To report bugs for Open Build Service, go to https://bugzilla.opensuse.org/, log in, and click New.
Mail: For feedback on the documentation of this product, you can also send a mail to doc-team@suse.com. Make sure to include the document title, the product version and the publication date of the documentation. To report errors or suggest enhancements, provide a concise description of the problem and refer to the respective section number and page (or URL).

3 Documentation Conventions #

The following notices and typographical conventions are used in this documentation:

/etc/passwd: directory names and file names
PLACEHOLDER: replace PLACEHOLDER with the actual value
PATH: the environment variable PATH
ls, --help: commands, options, and parameters
user: users or groups
package name : name of a package
Alt, Alt–F1: a key to press or a key combination; keys are shown in uppercase as on a keyboard
File, File › Save As: menu items, buttons
Dancing Penguins (Chapter Penguins, ↑Another Manual): This is a reference to a chapter in another manual.
Commands that must be run with root privileges. Often you can also prefix these commands with the sudo command to run them as non-privileged user.
```
root # command
geeko > sudo command
```
Commands that can be run by non-privileged users.
```
geeko > command
```
Notices
Warning: Warning Notice
Vital information you must be aware of before proceeding. Warns you about security issues, potential loss of data, damage to hardware, or physical hazards.
Important: Important Notice
Important information you should be aware of before proceeding.
Note: Note Notice
Additional information, for example about differences in software versions.
Tip: Tip Notice
Helpful information, like a guideline or a piece of practical advice.

4 Contributing to the Documentation #

The OBS documentation is written by the community. And you can help too!

Especially as an advanced user or an administrator of OBS, there will be many topics where you can pitch in even if your English is not the most polished. Conversely, if you are not very experienced with OBS but your English is good: We rely on community editors to improve the language.

This guide is written in DocBook XML which can be converted to HTML or PDF documentation.

To clone the source of this guide, use Git:

git clone https://github.com/openSUSE/obs-docu.git

To learn how to validate and generate the OBS documentation, see the file README.

To submit changes, use GitHub pull requests:

Fork your own copy of the repository.
Commit your changes into the forked repository.
Create a pull request. This can be done at https://github.com/openSUSE/obs-docu.

It is even possible to host instance-specific content in the official Git repository, but it needs to be tagged correctly. For example, parts of this documentation are tagged as <para os="opensuse">. In this case, the paragraph will only become visible when creating the openSUSE version of a guide.