From fc28462cea31fb9ac553483e827d293479b3a148 Mon Sep 17 00:00:00 2001 From: Nathan Cutler Date: Wed, 10 Jul 2024 17:17:41 +0200 Subject: [PATCH] xml: scripted rewrite of some xml:id values For SEO optimization, we need to avoid the use of dots ('.') and underscores ('_') in our xml:id values. Signed-off-by: Nathan Cutler --- xml/MAIN-obs.xml | 4 +- xml/art-obs-beginners-guide.xml | 120 +++--- xml/book-obs-user-guide.xml | 10 +- xml/factory.xml | 6 +- xml/obs_admin.xml | 2 +- xml/obs_admin_appliance.xml | 2 +- xml/obs_admin_backend.xml | 2 +- xml/obs_admin_components.xml | 2 +- xml/obs_admin_frontend.xml | 2 +- xml/obs_admin_integration.xml | 2 +- xml/obs_admin_tools.xml | 2 +- xml/obs_ag_administration.xml | 2 +- xml/obs_ag_installation_and_configuration.xml | 2 +- xml/obs_ag_k8s_worker.xml | 10 +- xml/obs_ag_overview_filesystem.xml | 2 +- xml/obs_ag_security_concepts.xml | 52 +-- xml/obs_ag_source_publish.xml | 8 +- xml/obs_ag_source_service.xml | 2 +- xml/obs_ag_troubleshooting.xml | 2 +- xml/obs_architecture.xml | 10 +- xml/obs_authorization_token.xml | 2 +- xml/obs_basic_workflow.xml | 88 ++--- xml/obs_best_practice_distribution_setup.xml | 2 +- xml/obs_best_practice_image_templates.xml | 6 +- xml/obs_best_practice_kiwi_editor.xml | 2 +- xml/obs_best_practice_maintained_release.xml | 2 +- xml/obs_best_practice_manage_group.xml | 2 +- xml/obs_best_practice_staging_workflow.xml | 2 +- xml/obs_binary_tracking.xml | 2 +- xml/obs_build_config.xml | 16 +- xml/obs_build_constraints.xml | 2 +- xml/obs_build_containers.xml | 6 +- xml/obs_build_preinstall.xml | 2 +- xml/obs_build_process.xml | 2 +- xml/obs_concepts.xml | 2 +- xml/obs_concepts_scm.xml | 2 +- xml/obs_cross_architecture_build.xml | 2 +- xml/obs_glossary.xml | 368 +++++++++--------- xml/obs_image_templates.xml | 6 +- xml/obs_maintenance_setup.xml | 20 +- xml/obs_moderation.xml | 10 +- xml/obs_motivation.xml | 12 +- xml/obs_multibuild.xml | 2 +- xml/obs_notifications.xml | 14 +- xml/obs_osc.xml | 16 +- xml/obs_package_formats.xml | 6 +- xml/obs_product_building.xml | 2 +- xml/obs_qa_hooks.xml | 2 +- xml/obs_request_and_review_system.xml | 2 +- xml/obs_scheduling_and_dispatching.xml | 2 +- xml/obs_scm_bridge.xml | 22 +- xml/obs_scm_ci_workflow_integration.xml | 148 +++---- xml/obs_signing.xml | 2 +- xml/obs_source_management.xml | 4 +- xml/obs_source_service.xml | 44 +-- xml/obs_staging_workflow.xml | 24 +- xml/obs_supported_formats.xml | 4 +- xml/obs_user_concept.xml | 2 +- xml/osc_building.xml | 8 +- 59 files changed, 553 insertions(+), 553 deletions(-) diff --git a/xml/MAIN-obs.xml b/xml/MAIN-obs.xml index affe1a03..764ccec9 100644 --- a/xml/MAIN-obs.xml +++ b/xml/MAIN-obs.xml @@ -7,7 +7,7 @@ %entities; ]> - - @@ -31,7 +31,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Target Audience This document is intended for users and developers interested in @@ -42,7 +42,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ toms 2017-08-03: Add some links to basic tutorials etc.? - + Conceptual Overview Created in 2005, the &obs; (&obsa;) is a generic system for building and @@ -53,7 +53,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ (&suse;, Debian, Ubuntu, Red Hat, Windows, etc.) and hardware architectures (&x86;, &amd64;, &zseries;, &ppc; etc.). - + Build Recipe To create a package in &obsa;, you need a build recipe @@ -106,7 +106,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ class="extension">.spec. - + Build Hosts and Packages The &obsa; server provides a Web interface and an API. The API is @@ -139,10 +139,10 @@ https://www.suse.com/communities/blog/suse-studio-integration/ scope of this guide. - The schematic in shows the components + The schematic in shows the components in context. -
+
Conceptual Overview of &obs; @@ -151,7 +151,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/
- + Projects and Packages In &obsa;, packages are organized in projects. @@ -192,14 +192,14 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Requirements for Working with the &osccmd; Command-Line Tool Before you start working with &obs;, make sure that the following requirements are met. - + Software Requirements @@ -249,7 +249,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Covered Scenarios This guide is based on the following assumptions. @@ -276,7 +276,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ You are using a customized system as shown in . + linkend="sec-obsbg-obsconfig"/>. All examples use the following elements. @@ -312,7 +312,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Setting up a home project using the &obsa; Web UI. @@ -320,7 +320,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Creating packages from a basic project hosted on &gh;. @@ -328,7 +328,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Patching source code without touching the original @@ -337,7 +337,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Branching a project, making changes, and submitting back @@ -357,7 +357,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ - + Configuring Your System for &obsa; While it is possible to use the &osccmd; tool without any @@ -376,7 +376,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ Follow the steps below to customize sudo. - + Configuring <command>sudo</command> To allow all users in the @@ -389,7 +389,7 @@ https://www.suse.com/communities/blog/suse-studio-integration/ This group will contain all users which are allowed to build packages: &prompt.root;groupadd osc - + Add users to your newly created group osc which are allowed to build packages: @@ -443,7 +443,7 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build - + Setting Up Your Home Project for the First Time This section shows how to set up your home project after @@ -459,7 +459,7 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build specific package. Setting up a home project is done as shown below. - + Adding Global Build Targets to Your Home Project @@ -512,7 +512,7 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build toms 2017-08-14: Maybe add a screenshot of the Web UI? - + Creating a New Project This section demonstrates how to create packages from a simple C++ project @@ -545,9 +545,9 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build To create a package from the upstream project, follow the steps below. - + - Set up your project as shown in . + Set up your project as shown in . @@ -600,32 +600,32 @@ Cmnd_Alias OSC_CMD = /usr/bin/osc, /usr/bin/build baseform="Spec File">spec file. The skeleton of such a spec file looks like this: - + Skeleton of a Spec File # # spec file for package &gitproject; # # -- Copyright omitted -- -Name: &gitproject; -Version: &gitprjvers; -Release: 0 -License: GPL-3.0 -Group: Documentation -Summary: Frobnication Tool -Url: &gitupstream1; -Source: &gitproject;-%{version}.tar.gz -BuildRequires: gcc -BuildRequires: cmake +Name: &gitproject; +Version: &gitprjvers; +Release: 0 +License: GPL-3.0 +Group: Documentation +Summary: Frobnication Tool +Url: &gitupstream1; +Source: &gitproject;-%{version}.tar.gz +BuildRequires: gcc +BuildRequires: cmake BuildRoot: %{_tmppath}/%{name}-%{version}-build -%description +%description This tool frobnicates the bar with the foo when choosing the baz. -%prep +%prep %setup -q -n %{name}-%{version} -%build -%install -%files +%files %defattr(-,root,root,-) %doc README LICENSE *.txt %{_bindir}/* -%changelog +%changelog - + The Header Metadata like package name, version, release, @@ -655,7 +655,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + Build Requirements Lists package dependencies that are required for building. @@ -665,25 +665,25 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Description Section Describes the purpose of the package and gives a comprehensive explanation. - + The Preparation Section Prepares the sources for building. This usually includes unpacking them with the %setup macro and patching them using the %patch macro. (For more information about patching, see - .) + .) - + The Build Section @@ -693,7 +693,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Install Section Contains commands or RPM macros which @@ -701,7 +701,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Files Section Lists all files and directories which belong to @@ -711,7 +711,7 @@ make install DESTDIR="$RPM_BUILD_ROOT"--> - + The Changelog Section This section is usually empty. Instead, &obsa; searches for a @@ -794,11 +794,11 @@ openSUSE_Tumbleweed x86_64 *.spec--> &prompt.user;osc buildlog openSUSE_Tumbleweed x86_64 - + Patching Source Code This section describes how to patch an upstream project. We use the same - project as shown in . + project as shown in . There are different reasons for patching a package. @@ -854,7 +854,7 @@ openSUSE_Tumbleweed x86_64 *.spec--> We assume that you already have a project as described in - . The project directory should look + . The project directory should look similar to this: project directory @@ -974,7 +974,7 @@ Patch0: &gitproject;_main.diff - + Branching a Package This section describes how to collaborate between projects. @@ -1017,7 +1017,7 @@ Patch0: &gitproject;_main.diff User &obsuser2; has to perform the following steps: - + Branching from a Project @@ -1039,7 +1039,7 @@ Patch0: &gitproject;_main.diff Make changes as shown in . + linkend="sec-obsbg-uc-patching"/>. @@ -1156,7 +1156,7 @@ Patch0: &gitproject;_main.diff If preferred, the below steps can also be performed using the OBS GUI. Requests can be managed under the Tasks tab. - + Dealing with Submit Requests Show all submit requests that belong to your home project @@ -1240,20 +1240,20 @@ Patch0: &gitproject;_main.diff When prompted, accept the GPG key of the download repository. - + Install the package: &prompt.root;zypper install &gitproject; - To update the package again, run . + To update the package again, run . You do not need to execute , as the repository is already configured in your system. - + Other Useful &osccmd; Commands The following list gives you a short overview of frequently used &osccmd; diff --git a/xml/book-obs-user-guide.xml b/xml/book-obs-user-guide.xml index a4afc0f8..6fc69093 100644 --- a/xml/book-obs-user-guide.xml +++ b/xml/book-obs-user-guide.xml @@ -44,11 +44,11 @@ see https://en.opensuse.org/openSUSE:Build_Service_Tutorial * Use CI services --> - + First Steps - + Concepts @@ -60,7 +60,7 @@ - + Usage @@ -79,7 +79,7 @@ - + Best Practices @@ -92,7 +92,7 @@ - + Reference diff --git a/xml/factory.xml b/xml/factory.xml index 3d660cf9..7981e542 100644 --- a/xml/factory.xml +++ b/xml/factory.xml @@ -6,12 +6,12 @@ + xml:id="cha-obs-factory" os="opensuse"> openSUSE Factory This chapter describes how the development of the future openSUSE distribution is done within OBS. - + openSUSE:Factory project The main project is openSUSE:Factory. This project is controlled by a small group which does review all submissions according to the policies. @@ -20,7 +20,7 @@ TBD - + Devel Projects The goal of openSUSE:Factory is to always have a working state. This is needed to allow all developer groups to use it as a base for testing diff --git a/xml/obs_admin.xml b/xml/obs_admin.xml index 307c8861..cff39c7d 100644 --- a/xml/obs_admin.xml +++ b/xml/obs_admin.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_appliance.xml b/xml/obs_admin_appliance.xml index bbcc7d90..f1f5ce40 100644 --- a/xml/obs_admin_appliance.xml +++ b/xml/obs_admin_appliance.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_backend.xml b/xml/obs_admin_backend.xml index a65c8b37..156a2fb7 100644 --- a/xml/obs_admin_backend.xml +++ b/xml/obs_admin_backend.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_components.xml b/xml/obs_admin_components.xml index 1d6fe1de..ed7ab0dd 100644 --- a/xml/obs_admin_components.xml +++ b/xml/obs_admin_components.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_frontend.xml b/xml/obs_admin_frontend.xml index 6bf38d58..c785274f 100644 --- a/xml/obs_admin_frontend.xml +++ b/xml/obs_admin_frontend.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_integration.xml b/xml/obs_admin_integration.xml index c45c1706..76055427 100644 --- a/xml/obs_admin_integration.xml +++ b/xml/obs_admin_integration.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_admin_tools.xml b/xml/obs_admin_tools.xml index 72ee5d40..7be29b56 100644 --- a/xml/obs_admin_tools.xml +++ b/xml/obs_admin_tools.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_ag_administration.xml b/xml/obs_ag_administration.xml index f0495f58..5319bc3d 100644 --- a/xml/obs_ag_administration.xml +++ b/xml/obs_ag_administration.xml @@ -6,7 +6,7 @@ + xml:id="obs-cha-administration"> Administration diff --git a/xml/obs_ag_installation_and_configuration.xml b/xml/obs_ag_installation_and_configuration.xml index 0ceb19ee..f54b0fc9 100644 --- a/xml/obs_ag_installation_and_configuration.xml +++ b/xml/obs_ag_installation_and_configuration.xml @@ -6,7 +6,7 @@ + xml:id="obs-cha-installation-and-configuration"> Installation and Configuration diff --git a/xml/obs_ag_k8s_worker.xml b/xml/obs_ag_k8s_worker.xml index b8cd9242..c4134b7b 100644 --- a/xml/obs_ag_k8s_worker.xml +++ b/xml/obs_ag_k8s_worker.xml @@ -16,7 +16,7 @@ So, /dev/kvm can be made available to containers via Kubernetes using device plugin API (). One of the implementations of K8s devices plugin for KVM is available here : - + Use the following manifest to deploy the KVM device plugin in a container. This plugin is packaged as k8s-device-plugin-kvm and corresponding container built here: @@ -58,13 +58,13 @@ spec: path: /var/lib/kubelet/device-plugins - + Build container image of the build service locally and load it to all worker nodes. There is sample project file here: docker load < "/path/to/docker.archive.tar.gz" - + Use the following manifest to deploy the build service worker. Here ports are hard-coded to allow easy integration with local kubelet without requiring a separate ingress-controller @@ -139,7 +139,7 @@ spec: nodePort: 32516 - + Save the following into a file launchworker.sh. Later use this file to launch the worker. Make sure you uncomment the OBS_REPO_SERVERS line and change the IP address to your build servers address cat << EOH > /etc/buildhost.config @@ -159,7 +159,7 @@ EOH obsworker restart - + Use the following command to launch the build service worker. cat launchworker.sh | kubectl exec -i -t test-worker-pod bash diff --git a/xml/obs_ag_overview_filesystem.xml b/xml/obs_ag_overview_filesystem.xml index 7dbc8b95..3cbf6f79 100644 --- a/xml/obs_ag_overview_filesystem.xml +++ b/xml/obs_ag_overview_filesystem.xml @@ -6,7 +6,7 @@ + xml:id="obs-cha-overview-filesystem"> File System Overview diff --git a/xml/obs_ag_security_concepts.xml b/xml/obs_ag_security_concepts.xml index 71c000b8..ea0d9148 100644 --- a/xml/obs_ag_security_concepts.xml +++ b/xml/obs_ag_security_concepts.xml @@ -6,11 +6,11 @@ + xml:id="obs-cha-security-concepts"> Security Concepts - + General Paradigm The general paradigm of &obs; is to host all content on its own. Every part required to rebuild a package is hosted in &obs; to guarantee reproducibility. @@ -18,11 +18,11 @@ However, optional services to integrate remote resources exist as well. These resources are either mirrored and stored in revision control system or just cached. - + Frontend The API and web interface frontends is the only part which must be accessible from public network. A SSL/TLS certificate is highly recommended. - + Access to Mirror Servers The following services require access to stage servers. These servers can be used to publish content without the need to make &obs; server parts @@ -40,7 +40,7 @@ - + Access to the Public Network The following services may require access to the public network. @@ -67,14 +67,14 @@ - + Worker network It is recommended to run the &obs; workers in an isolated network. This is an additional security mechanism in case of a security breach on a worker. This network needs access to the source and repository servers of the &obs; backend, but nowhere else. - + Signer network It is recommended to run the signd on an isolated host. The signer services need to stay on the &obs; backend servers, they are just used for scheduling @@ -88,7 +88,7 @@ backend server components (source server and publisher). - + Build Environment The build environment is created by obsworker instances via the build script. Inside the build instances unverified and potentially harmful code is executed. @@ -112,7 +112,7 @@ source packages are rebuildable without root permissions. - + Source Revision System The source revision storage system is part of &obs;. The identification of sources still happens using MD5 sums for historic reasons. MD5 is considered to be still @@ -126,7 +126,7 @@ builds, but it should be avoided for base projects. - + Permission Handling Authorization for write operations is done via the maintainer role on package or project level. On project level the projects are organized in namespaces @@ -136,7 +136,7 @@ top level namespaces (for example, openSUSE: namespace in our reference instance). - + Signature Handling Signatures are used to proof the origin of a shipment independent of &obs; instance. Once the signd daemon has @@ -181,17 +181,17 @@ - + Trust Zones &OBS; components deal with different trust zones. These are separated via network or virtualization mechanics. - + Public Zones Public zones are areas where any code under user control is running. - + External Network This can be the public Internet if the &obs; instance is a public @@ -201,7 +201,7 @@ connections to the Internet as described below. - + Untrusted Code All code which is used to build content is considered @@ -230,7 +230,7 @@ the source server only. - + &obs; Frontend Background Services &obs; frontend background services handle less time critical operations. @@ -238,7 +238,7 @@ trackers, sending notifications or long running jobs. - + Stage Server The stage server is providing the public content of the &obs; backends. @@ -246,7 +246,7 @@ a mirror infrastructure. - + Cloud Uploader The cloud uploader is uploading build results on user request. It reads @@ -255,7 +255,7 @@ This is an optional service. - + Source Service Server The source service server is acting based on uploaded sources. The @@ -266,12 +266,12 @@ - + Internal Zone The internal zone is running service which are supposed to work without further external dependency. - + &obs; Source Server The source server coordinates changes to package and project configuration. @@ -281,7 +281,7 @@ There can only be a single source server per OBS install. - + &obs; Binary Servers Binary Servers are hosting all content of build results. They @@ -289,7 +289,7 @@ staging server. - + External Dependencies The internal zone has no external dependency. @@ -300,19 +300,19 @@ - + Worker Zone The &obs; workers are running in an own isolated network. They access only source and binary servers from internal zone. - + Signing Server The signing server is supposed to be the most isolated service. It is supposed to be stateless after initial setup. Avoid to enable any remote access. -
+
Trust Zones of &obs; diff --git a/xml/obs_ag_source_publish.xml b/xml/obs_ag_source_publish.xml index a5a4267f..c50af687 100644 --- a/xml/obs_ag_source_publish.xml +++ b/xml/obs_ag_source_publish.xml @@ -6,7 +6,7 @@ + xml:id="source-publish"> Source Publisher The job of the source publish service is to publish all sources for directly before published binaries. This will include the sources of repackaged @@ -14,7 +14,7 @@ binaries. For example, the sources of RPMs which are used inside of product, appliance or container images. A prerequisite for this is that OBS has enabled content tracking for the used projects. - + Configuring Source Publisher The source publishing can be configured via the file /usr/lib/obs/server/BSConfig.pm, where it can be @@ -26,7 +26,7 @@ content tracking for the used projects. our $sourcepublish_filter = [ "openSUSE:.*", "SUSE:.*" ]; - + Considerations The source publishing service is publishing the sources as they are hosted in &obs;. This means these are the unprocessed sources and the content is not identical to the @@ -35,7 +35,7 @@ content tracking for the used projects. As a consequence hints like NoSource: tags in spec files are ignored. The only way to disable publishing for the user is to disable access or sourceaccess via the flags. - The filesystem structure is $project/$package/$srcmd5/. A + The filesystem structure is $project/$package/$srcmd5/. A inside of binary builds can be used to find the right sources. &obs; will care for de-duplication on the rsync server. This must get implemented there. diff --git a/xml/obs_ag_source_service.xml b/xml/obs_ag_source_service.xml index f5be344c..1510beae 100644 --- a/xml/obs_ag_source_service.xml +++ b/xml/obs_ag_source_service.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_ag_troubleshooting.xml b/xml/obs_ag_troubleshooting.xml index c7ffb47f..3144a141 100644 --- a/xml/obs_ag_troubleshooting.xml +++ b/xml/obs_ag_troubleshooting.xml @@ -6,7 +6,7 @@ + xml:id="obs-cha-troubleshooting"> Troubleshooting diff --git a/xml/obs_architecture.xml b/xml/obs_architecture.xml index 641af8b7..cb4d8889 100644 --- a/xml/obs_architecture.xml +++ b/xml/obs_architecture.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -19,8 +19,8 @@ Overview Graph &OBS; is not a monolithic server; it consists of multiple daemons - that fulfill different tasks (see ). -
+ that fulfill different tasks (see ). +
Simplified OBS Component Overview @@ -222,7 +222,7 @@ other back-end components. -
+
OBS Communication (Simplified) @@ -234,7 +234,7 @@
- The figure shows the + The figure shows the communication flow between the &obsa; components if a package source (for example, a _service file) was updated: diff --git a/xml/obs_authorization_token.xml b/xml/obs_authorization_token.xml index 8f4140c4..0dd196de 100644 --- a/xml/obs_authorization_token.xml +++ b/xml/obs_authorization_token.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_basic_workflow.xml b/xml/obs_basic_workflow.xml index 9b19c62b..ea3da410 100644 --- a/xml/obs_basic_workflow.xml +++ b/xml/obs_basic_workflow.xml @@ -4,7 +4,7 @@ %entities; ]> - @@ -18,7 +18,7 @@ TBD --> - + Setting Up Your Home Project toms 2017-08-25: Suggestion by sknorr: generic section plus home project (cross refs only) @@ -27,7 +27,7 @@ This section shows how to set up your home project with the command line tool &osccmd;. For more information about setting up your home project with the Web UI, see - . + . This chapter is based on the following assumptions: @@ -41,19 +41,19 @@ - You have installed &osccmd; as described in . + You have installed &osccmd; as described in . - You have configured &osccmd; as described in . + You have configured &osccmd; as described in . Setting Up Your Home Project - + Get a list of all available build targets of your &obsa; instance: @@ -66,7 +66,7 @@ openSUSE:Tools, openSUSE:Templates. - + Configure your build targets with: @@ -102,7 +102,7 @@ Add more repository elements as needed. Insert the information - from into the + from into the project attribute. @@ -142,7 +142,7 @@ is valid, &osccmd; will save it. Otherwise, it will show an error and prompt you whether to Try again?. In this case, press n. Your changes will be lost and you will need to start - from again. + from again. @@ -159,7 +159,7 @@ assume that this project contains source code which you want to package for one or more &suse; (openSUSE) distributions. We assume the setup of your home project in your &obsa; instance is - already done. If not, refer to . + already done. If not, refer to . To create a package from the upstream project, do the following: @@ -303,7 +303,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; -->openSUSE_Tumbleweed x86_64 *.spec - If you encounter problems, see . + If you encounter problems, see . @@ -343,7 +343,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + Investigating the Local Build Process toms 2017-08-22: https://en.opensuse.org/openSUSE:Build_Service_Tutorial#Correct_Errors_in_the_Local_Build_Process @@ -353,16 +353,16 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + - + toms 2017-08-22: Troubleshooting? - + Build Log Each build produces a log file on &obsa;. This log file can be viewed by @@ -412,7 +412,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + Local Build Root Directory If you build a package locally and you get a build error, investigate @@ -444,30 +444,30 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; The build root contains the following structure: - + Directory Structure of a Build Root (<filename>/var/tmp/build-root/</filename>) /home/abuild/ └── rpmbuild - ├── BUILD - ├── BUILDROOT - ├── OTHER - ├── RPMS + ├── BUILD + ├── BUILDROOT + ├── OTHER + ├── RPMS │ ├── i386 │ ├── noarch │ └── x86_64 - ├── SOURCES - ├── SPECS - └── SRPMS + ├── SOURCES + ├── SPECS + └── SRPMS toms 2017-08-22: https://rpm-packaging-guide.github.io/#rpm-packaging-workspace - + Contains directory named after the package name. In spec files, the name of the package directory is referenced using the %buildroot macro. - + If the build process was unable to create a package, this directory contains all files and directories which are installed in the target @@ -479,12 +479,12 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; emptied. - + Usually contains the file rpmlint.log. - + If the build was successful, stores binary RPMs into subdirectories of architecture @@ -492,17 +492,17 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; x86_64). - + All source files from the working copy will be copied here. - + toms 2017-08-22: empty? - + Stores source RPMs into this directory. @@ -534,24 +534,24 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; - + - + (layering) - + (linking and aggregating) - + Adding Dependencies to Your Build Recipes toms 2017-08-24: Should probably go into the concept part? toms 2017-08-24: should we explain hard and soft requirements? @@ -561,7 +561,7 @@ Fri Aug 23 08:42:42 UTC 2017 - &exampleuser_mail; requirements). Both belong to the header of the spec file. - + Excerpt of Build and Installation Requirements Name: foo-example Version: 1.0.0 @@ -570,7 +570,7 @@ Requires: zool >= 1.5.6 toms 2017-08-24: Version compare with zypper vcmp? - + Associating Other Repositories with Your Repository There is no need to duplicate the work of others. If you need a specific @@ -597,7 +597,7 @@ Requires: zool >= 1.5.6 &prompt.user;osc meta prj --edit &obshome1; - + Search for repository elements. For example, to allow usage packages from devel:languages:python in a @@ -628,7 +628,7 @@ Requires: zool >= 1.5.6 - + Add more path elements under the same repository element. @@ -636,14 +636,14 @@ Requires: zool >= 1.5.6 - If necessary, repeat and - to add path + If necessary, repeat and + to add path elements to repository elements of other distributions or releases. - + Reusing Packages in Your Project toms 2017-08-30: This part and its subsections needs to be further discussed. "Aggregate" as a word doesn't really fit with the @@ -657,7 +657,7 @@ Requires: zool >= 1.5.6 toms 2017-08-30: add a notes when NOT to use the two methods. - + Aggregating a Package An aggregate package is a pointer to an &obsa; package. @@ -706,7 +706,7 @@ Requires: zool >= 1.5.6 contains the _aggregate file. - + Linking a Package A linked package is a clone of another package with diff --git a/xml/obs_best_practice_distribution_setup.xml b/xml/obs_best_practice_distribution_setup.xml index 222d912a..f4a2f2f8 100644 --- a/xml/obs_best_practice_distribution_setup.xml +++ b/xml/obs_best_practice_distribution_setup.xml @@ -12,7 +12,7 @@
General Project Setup for a Maintained Distribution - are the + are the
diff --git a/xml/obs_best_practice_image_templates.xml b/xml/obs_best_practice_image_templates.xml index ec49707b..d51b6ec8 100644 --- a/xml/obs_best_practice_image_templates.xml +++ b/xml/obs_best_practice_image_templates.xml @@ -4,14 +4,14 @@ %entities; ]> - Image Templates &image_template_introduction_paragraph; + xpointer="image-template-introduction-paragraph"/>--> How you can create your own image templates will be shown here.
&obsa; Templates Page @@ -71,7 +71,7 @@ &kiwi; configurations usually consists of an xml configuration root tarball. + xpointer="image-template-icon-paragraph"/>--> &image_template_icon_paragraph; For a full list of image descriptions and general information about building images with KIWI, see the %entities; ]> - diff --git a/xml/obs_best_practice_maintained_release.xml b/xml/obs_best_practice_maintained_release.xml index 5933fe0c..d814c179 100644 --- a/xml/obs_best_practice_maintained_release.xml +++ b/xml/obs_best_practice_maintained_release.xml @@ -12,7 +12,7 @@
General Project Setup for a Maintained Distribution - are the + are the
diff --git a/xml/obs_best_practice_manage_group.xml b/xml/obs_best_practice_manage_group.xml index fe18bc1c..6a2ccb25 100644 --- a/xml/obs_best_practice_manage_group.xml +++ b/xml/obs_best_practice_manage_group.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_best_practice_staging_workflow.xml b/xml/obs_best_practice_staging_workflow.xml index 71f1b421..79cc1fb0 100644 --- a/xml/obs_best_practice_staging_workflow.xml +++ b/xml/obs_best_practice_staging_workflow.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_binary_tracking.xml b/xml/obs_binary_tracking.xml index 669c60c9..5417bf9f 100644 --- a/xml/obs_binary_tracking.xml +++ b/xml/obs_binary_tracking.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_build_config.xml b/xml/obs_build_config.xml index 00bcbd61..6e358fe3 100644 --- a/xml/obs_build_config.xml +++ b/xml/obs_build_config.xml @@ -3,14 +3,14 @@ %entities; ]> - Build Configuration - + About the Build Configuration Each project has a build configuration which @@ -93,7 +93,7 @@ - + Configuration File Syntax The syntax is basically the same as in RPM spec files. @@ -128,7 +128,7 @@ The following list contains a list of allowed keywords in the build configuration (prjconf): - + Available Keywords in Build Configuration @@ -948,7 +948,7 @@ Support: pax debbuild - + Building with ccache or sccache The usage of ccache or sccache can be enabled for each package by @@ -987,7 +987,7 @@ Support: pax debbuild - + Macro Definitions in the Build Configuration You can use rpm macro definitions in the build configuration (prjconf) to improve @@ -1046,7 +1046,7 @@ Support: pax debbuild - + Macros for the Build Configuration Only To specify macros for the building process, use the %define @@ -1061,7 +1061,7 @@ Support: pax debbuild the build configuration. - + Macros Used in Spec Files Only To define the values of macros used in spec files, `%define` is %entities; ]> - diff --git a/xml/obs_build_containers.xml b/xml/obs_build_containers.xml index 69689472..6d584982 100644 --- a/xml/obs_build_containers.xml +++ b/xml/obs_build_containers.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -84,7 +84,7 @@ Flatpak packages can be built in the Open Build Service, see - for further details. + for further details. @@ -102,7 +102,7 @@ Mkosi allows building images for rpm, arch, deb, and gentoo based distributions, see - for further details. + for further details. diff --git a/xml/obs_build_preinstall.xml b/xml/obs_build_preinstall.xml index 92755eb4..1a99629b 100644 --- a/xml/obs_build_preinstall.xml +++ b/xml/obs_build_preinstall.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_build_process.xml b/xml/obs_build_process.xml index 2068ee53..bbe538bf 100644 --- a/xml/obs_build_process.xml +++ b/xml/obs_build_process.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_concepts.xml b/xml/obs_concepts.xml index 6c81e463..647a1d59 100644 --- a/xml/obs_concepts.xml +++ b/xml/obs_concepts.xml @@ -4,7 +4,7 @@ %entities; ]> - diff --git a/xml/obs_concepts_scm.xml b/xml/obs_concepts_scm.xml index 79ccab78..49d9a223 100644 --- a/xml/obs_concepts_scm.xml +++ b/xml/obs_concepts_scm.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_cross_architecture_build.xml b/xml/obs_cross_architecture_build.xml index 5a13a5d9..8b780757 100644 --- a/xml/obs_cross_architecture_build.xml +++ b/xml/obs_cross_architecture_build.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_glossary.xml b/xml/obs_glossary.xml index 8b017736..6b75511b 100644 --- a/xml/obs_glossary.xml +++ b/xml/obs_glossary.xml @@ -10,21 +10,21 @@ ******* Please post on the OBS mailing list your suggestion, if you ******** ******* are unsure. ******** --> - Glossary - + Announcement TBD - + &obs.ai; @@ -34,7 +34,7 @@ - + API @@ -48,7 +48,7 @@ - + Appliance @@ -58,22 +58,22 @@ Appliances can be copied as-is onto a hard disk, an SSD, or started as a virtual machine (deployed). - - + + - + Archive (Archive File) An archive file contains a representation of usually multiple files and directories. Usually, archive files are also compressed. Archive files are the basis for binary packages - (). + (). - + Attribute @@ -85,7 +85,7 @@ - + Binary Package (Binary) @@ -109,16 +109,16 @@ human-readable like a script, usually does not matter). - sknorr, 2017-08-30 - - - - - - - + + + + + + + - + Branch @@ -127,10 +127,10 @@ repository. You can either delete the branch or merge it into the original repository with a submit request. - + - + Bug @@ -138,7 +138,7 @@ - + Bugowner + + - + Build Requirement @@ -198,18 +198,18 @@ For example, a C++ program needs the C++ compiler included in the gcc package. - - + + - + Build Result The current state of a package. Example of a build result could be succeeded, failed, blocked, etc. - + Build Root @@ -217,10 +217,10 @@ packages. By default, the build root is located in /var/tmp/build-root/BUILD_TARGET. - + - + Build Target @@ -229,7 +229,7 @@ - + Changelog @@ -237,10 +237,10 @@ can contain information about version updates, bug and security fixes, incompatible changes, or changes related to the distribution. - + - + .changes File @@ -248,10 +248,10 @@ In &obsa;, a file with the file extension .changes to store changelog information. - + - + Commit @@ -259,10 +259,10 @@ the author, the date and time, a commit checksum, an optional request number, and a log message. - + - + Container @@ -275,25 +275,25 @@ system. Unlike binary packages, containers are deployed and not installed. Formats of containers include &appimg;, &docker;, &snap;, and &flatpak;. - - - + + + - + Deb A package format created and used by the Debian distribution. - - + + - + Decision @@ -302,18 +302,18 @@ - + Description TBD - + Dependency - + - + Devel Project @@ -321,11 +321,11 @@ the devel project devel:languages:python stores all packages related to the Python programming language. - - + + - + Docker @@ -333,10 +333,10 @@ Docker is a lightweight virtualization solution to run multiple virtual units (containers) simultaneously on a single control host. - + - + Download Repository @@ -348,11 +348,11 @@ - + Diff - + - + DISTURL @@ -384,7 +384,7 @@ - + EULA @@ -395,11 +395,11 @@ - + Fix - + - + Flags @@ -409,15 +409,15 @@ - + GA Project The GA (general availability) project builds an initial release of a product. It gets frozen after releasing the product. All further updates get released via the of this project. + linkend="obs-glos-update-project"/> of this project. - + GPG Key @@ -427,27 +427,27 @@ - + Home Project Working area in OBS for uploading and building packages. Each home project starts with home:USERNAME. - + - + Home Repository TBD - - + + - + Image (Image File) @@ -456,12 +456,12 @@ multiple types of image: - - + + - + Image Description @@ -470,10 +470,10 @@ *.kiwi), scripts, or configuration data to customize certain parts of the &kiwi; build process. - + - + Incident Describes a specific problem and the @@ -482,7 +482,7 @@ maintenance incident project and the update get built here. - + Installation Requirement @@ -491,7 +491,7 @@ - + &kiwi; @@ -499,31 +499,31 @@ create images for Linux supported hardware platforms or for virtualization systems. - + - + License Written contract to specify permissions for use and distribution of software. - + - + Link A concept that defines a relationship between a source and a target repository. - + - + Maintainer @@ -532,26 +532,26 @@ add, modify, and remove packages and subprojects, accept submit requests, and change metadata. - + - + Maintenance Project A project without sources and binaries, defined by the maintenance team. Incidents are created as sub projects of this project. - + - + Maintenance Request TBD - + Metadata @@ -559,7 +559,7 @@ - + &obsa; Package @@ -583,7 +583,7 @@ - + &OBS; @@ -597,15 +597,15 @@ - + &osbs; A specific Web service instance of from the &opensuse; project at + linkend="obs-glos-obs"/> from the &opensuse; project at . - + &osccmd; @@ -613,12 +613,12 @@ stands for openSUSE commander. &osccmd; works similarly to SVN or Git. - + - + Operating System Image @@ -627,20 +627,20 @@ Depending on their purpose, operating system images are classified into: - - - + + + Formats of operating system images include ISO, Virtual Disk, and PXE Root File System. - - - + + + - + Overlay File @@ -652,31 +652,31 @@ system (overlaid) of the appliance root. This includes permissions and attributes as a supplement. - - - + + + - + Package &obsa; handles very different types of software package: - - - + + + - + - + Package Requirement - + - + Package Repository A place where installable packages are available. This can @@ -691,16 +691,16 @@ - + Patch Textual differences between two versions of a file. - + - + Patch File @@ -708,17 +708,17 @@ class="extension">.diff or .patch. - + - + Patchinfo TBD - + Product Image @@ -729,11 +729,11 @@ Live images are a special case of operating system images. They can be run directly a USB disk or DVD and are often but not always installable. - - + + - + Project @@ -742,7 +742,7 @@ - + Project Configuration @@ -750,21 +750,21 @@ on or off certain features during the build or to handle circular dependencies. - + - + Publishing Finished process when a package is successfully built and available in the download repository. - + - + Release Project A release project is hosting a release repository which is not @@ -773,17 +773,17 @@ - + Repository A distribution-specific area that holds dependencies required for building a package. - + - + Repo File @@ -792,56 +792,56 @@ name of the repository, the repository type, and references to the download repository and the GPG key. - + - + Request TBD - + Requirement In the &obsa; context, package requirements that are needed to create, build, or install a package. - - + + - + Revision A unique numeric identifier of a commit. - + - + RPM A package format. It stands for recursive acronym RPM Package Manager. Mainly used by &suse;, Red Hat, u.a. - - + + - + Sandbox Isolated region of a host system which runs either a virtual machine or a change root environment. - + - + Service File @@ -851,7 +851,7 @@ - + Spec File @@ -859,32 +859,32 @@ a general package description and dependencies required for building and installing the package. - - - + + + - + Status Monitor TBD - + Source Original form, mostly written in a computer language. - + - + Source Link - + - + Source Package @@ -897,20 +897,20 @@ An example of source packages are SRPMs which contain the source for accompanying &rpmf; binary packages. - - + + - + Source Service A tool to validate, generate, or modify a source in a trustable way. - + - + &suse; Package Hub @@ -920,14 +920,14 @@ - + System Status TBD - + Submit Request @@ -935,17 +935,17 @@ - + Subproject A child of a parent project. - - - + + + - + Target @@ -956,20 +956,20 @@ - + Update Project A project which provides official updates for the products generated - in the . The update project usually + in the . The update project usually links sources and repositories against the . + linkend="obs-glos-ga-project"/>. - - + + - + Virtual Machine Image @@ -978,12 +978,12 @@ computer and run as-is. As such, there is some overlap between virtual machine images and appliances. - - + + - + Watchlist @@ -992,11 +992,11 @@ - + Working Copy - + - + Working Directory @@ -1007,7 +1007,7 @@ - + &zypper; diff --git a/xml/obs_image_templates.xml b/xml/obs_image_templates.xml index 0f05246b..f0019017 100644 --- a/xml/obs_image_templates.xml +++ b/xml/obs_image_templates.xml @@ -3,14 +3,14 @@ %entities; ]> - Image Templates &image_template_introduction_paragraph; - toms 2017-08-17: Integrate some sections/text from here http://docserv.suse.de/documents/Open_Build_Service/obs-best-practices/html/cha.obs.best-practices.localsetup.html @@ -43,7 +43,7 @@ ~/bin directory, and make the file executable. - + Configuring &osc; Usually, the default configuration is appropriate in most cases. There are some special configuration option which might be helpful @@ -147,10 +147,10 @@ - + Usage - + Getting Help @@ -164,7 +164,7 @@ - + Using &osccmd; for the First Time When you use the &osccmd; command for the first time, the command will @@ -206,7 +206,7 @@ authenticated it. - + Overview of Brief Examples The &osccmd; command is similar to git: @@ -236,7 +236,7 @@ Which &obsa; instance it shows depends on the option in the configuration file. By default, the &opensuse; Build Server is used. If you need another server, use the - option as shown in . + option as shown in . diff --git a/xml/obs_package_formats.xml b/xml/obs_package_formats.xml index 58c8f2b8..4721861f 100644 --- a/xml/obs_package_formats.xml +++ b/xml/obs_package_formats.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -286,7 +286,7 @@ systemctl enable sshd toms 2017-08-18: TODO What is it and what is needed - + &flatpak; The Flatpak format can be used @@ -418,7 +418,7 @@ Support: kmod-compat kernel-default perl-YAML-LibYAML - + mkosi Mkosi allows diff --git a/xml/obs_product_building.xml b/xml/obs_product_building.xml index 51559388..47339dd2 100644 --- a/xml/obs_product_building.xml +++ b/xml/obs_product_building.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_qa_hooks.xml b/xml/obs_qa_hooks.xml index f5cc2976..3ca28f83 100644 --- a/xml/obs_qa_hooks.xml +++ b/xml/obs_qa_hooks.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_request_and_review_system.xml b/xml/obs_request_and_review_system.xml index 93cbf513..aa45e4d6 100644 --- a/xml/obs_request_and_review_system.xml +++ b/xml/obs_request_and_review_system.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_scheduling_and_dispatching.xml b/xml/obs_scheduling_and_dispatching.xml index 8c3a8888..177ff0a8 100644 --- a/xml/obs_scheduling_and_dispatching.xml +++ b/xml/obs_scheduling_and_dispatching.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_scm_bridge.xml b/xml/obs_scm_bridge.xml index e2f660d3..b722fac8 100644 --- a/xml/obs_scm_bridge.xml +++ b/xml/obs_scm_bridge.xml @@ -3,7 +3,7 @@ %entities; ]> - SCM Bridge - + SCM Bridge - + Introduction The SCM bridge allows the sources of a single package or an entire project @@ -44,7 +44,7 @@ allow OBS to follow the sources automatically. - + Setup a package using the scm bridge The setup is purely done in package meta by defining the SCM URL inside of the scmsync tag: @@ -67,7 +67,7 @@ - + Setup an entire project using the SCM bridge An entire project can be setup by defining the scmsync tag in project meta data. Every top level @@ -85,7 +85,7 @@ <scmsync>https://gitlab.com/some/repository?onlybuild=glibc&onlybuild=kernel</scmsync> - + Implementation and Limitations The sources are currently cloned for the OBS source server to allow OBS to process them. This @@ -112,7 +112,7 @@ <scmsync>https://gitlab.com/some/repository?subdir=MY_SUBDIRECTORY</scmsync> - + Using a specific revision, tag or branch The URL can define a revision, tag or branch via an URL fragment. This means the URL can get extended by a @@ -126,7 +126,7 @@ - + Converting to a project git A project git repository is mostly the same as any project for the pbuild tool. The command # osc create-pbuild-config @@ -137,7 +137,7 @@ - + Forking a scmsync package The OBS server allows to create a cloned project with another package using a specified SCM repository. This can be used by tooling to create forked test builds for merge requests. @@ -148,11 +148,11 @@ - + SCM Source Updates The OBS instance needs to get notified on any change in the SCM server. There are two ways to achieve this. - One way is via single configurations for each git repository as documented in the documentation. + One way is via single configurations for each git repository as documented in the documentation. An alternative way is to configure it globally. This requires admin permissions on the git hosting side and another bridge implementation. The advantage is that any used repository will be synced automatically just by referencing it via the scmsync meta tag. diff --git a/xml/obs_scm_ci_workflow_integration.xml b/xml/obs_scm_ci_workflow_integration.xml index 3c7893e4..8418bd46 100644 --- a/xml/obs_scm_ci_workflow_integration.xml +++ b/xml/obs_scm_ci_workflow_integration.xml @@ -3,7 +3,7 @@ %entities; ]> - SCM/CI Workflow Integration - + SCM/CI Workflow Integration Setup - + Introduction With this integration, you can take advantage of source code management (SCM) @@ -33,11 +33,11 @@ constantly mentioning all the names for the same things, e.g. Pull Requests/Merge Requests, is tiresome and confusing. However, every aspect has its correspondence in GitLab and Gitea. Refer to + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-equivalence-table"/> for clarification of terminology. - + Prerequisites Before you start, you need to @@ -53,7 +53,7 @@ - + Supported SCMs We support the GitHub.com and GitLab.com instances. @@ -63,13 +63,13 @@ with that SCM. - + Token Authentication OBS and GitHub need to talk to each other. Tokens are the way to make this happen. - + How to Authenticate OBS with SCMs You have to create a GitHub personal @@ -115,14 +115,14 @@ documentation to learn how. - + How to Authenticate SCMs with OBS You have to create an OBS workflow token. Github is going to use it to trigger actions on OBS on your behalf. - + Create Token You can create the OBS token via WebUI in Profile @@ -144,14 +144,14 @@ Make sure you replace long_ascii_salad with your real GitHub personal access token created in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication-how-to-authenticate-obs-with-scm"/> Don't forget to keep your token secret to prevent someone else from triggering operations in your name! - + Regenerating Secrets and Deleting Tokens If you suspect your OBS token secret was leaked, you can regenerate @@ -174,19 +174,19 @@ osc token --delete $token_id # remove the token with the given id Then you can create a new one as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication-how-to-authenticate-scm-with-obs"/> and replace it wherever you use it. - + Webhooks Once OBS and GitHub are allowed to speak to each other, they can start talking via webhooks. - + SCM Events On a GitHub repository, events are happening all the time: a @@ -264,7 +264,7 @@ - Refer to the for more details or read more about Refer to the for more details or read more about GitHub events, GitLab @@ -274,7 +274,7 @@ events. - + How to Set Up a Webhook on Github Go to the project you want to set the integration on, then under @@ -322,7 +322,7 @@ - + How to Set Up a Webhook on GitLab Go to the project you want to set the integration on, under @@ -362,7 +362,7 @@ - + How to Set Up a Webhook on Gitea Go to the repository you want to set the integration on, then under @@ -411,7 +411,7 @@ - + OBS Workflows A GitHub event occurs and OBS receives the corresponding webhook. @@ -427,7 +427,7 @@ a directory .obs which contains a file called workflows.yml. If you don't want to use that directory, you should check - out. + out. The content of .obs/workflows.yml could look @@ -465,7 +465,7 @@ rebuild_master: only: - master - + Configuration File Location By default the configuration file is fetched from the repository's @@ -498,7 +498,7 @@ rebuild_master:
- + OBS Workflow Steps We support the following steps (the keys used in the @@ -540,7 +540,7 @@ rebuild_master: branch a package, link packages, configure repositories/architectures, rebuild packages and trigger services of a package. - + Branch a Package in a Project Given we have a source package called @@ -581,7 +581,7 @@ rebuild_master: configure_repositories step, set the add_repositories key to anything else than enabled. - + Submit a Request The submit request step is the equivalent of the osc submitrequest command. @@ -628,7 +628,7 @@ rebuild_master: description: 'Check out this cool package' # (optional, uses the commit/pull request message if not set) - + Link a Package to a Project The link package step is the equivalent of osc @@ -670,13 +670,13 @@ rebuild_master: target_project: home:jane - If you rely on + If you rely on to run, for instance to pick up changes from a PR with the obs_scm service, you can't make use of this step. Package links do not run the services. Use the branch_package step instead. - + Configure Repositories/Architectures for a Project Given a project called home:jane, the step will @@ -741,7 +741,7 @@ rebuild_master: - x86_64 - + Rebuild a Package Given a project called home:Admin and a @@ -758,12 +758,12 @@ rebuild_master: package: ctris - + Set Flags for Projects, Packages, Repositories or Architectures There are OBS-wide defaults for each flag type. This step is only necessary if you want to diverge from the defaults (see - ). + ). Providing the type build, the status enable and the project home:Admin, OBS will enable all builds: @@ -797,7 +797,7 @@ rebuild_master: set_flags step, although this isn't necessary as long as they exist. The type has to be one of the following values: - + Valid flag types lock (default status disable) build (default status enable) @@ -831,7 +831,7 @@ rebuild_master: architecture: x86_64 - + Trigger Services of a Package Given a project called home:Admin and a @@ -851,7 +851,7 @@ rebuild_master: - + Filters You can customize when workflows run by declaring @@ -874,7 +874,7 @@ rebuild_master: - master - staging - + Filters Delimiters: only and ignore Some steps can affect a group of elements (branches) @@ -930,11 +930,11 @@ rebuild_master: - staging - + Event Filter Setting an event filter will run the workflow only for this event. The event filter doesn't accept multiple events. - Documentation on the SCM events can be found here: . + Documentation on the SCM events can be found here: . The available event filters are: @@ -946,7 +946,7 @@ rebuild_master: merge_request is an alias for the - 'pull_request' event. Introduced with workflow version 1.1 (also see ). + 'pull_request' event. Introduced with workflow version 1.1 (also see ). . @@ -974,7 +974,7 @@ rebuild_master: event: pull_request - + Branches Filter Matches target branches based on their names and runs a @@ -997,7 +997,7 @@ rebuild_master: - final Learn more about . + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-obs-workflows-filters-delimiters"/>. @@ -1008,7 +1008,7 @@ rebuild_master: - + Placeholder Variables With placeholder variables, workflows are now dynamic. Whenever a @@ -1057,11 +1057,11 @@ test_build: For a more in-depth example in combination with configuration file location, refer to - . + . - + Status Reporting Once all the steps in the workflow are done, OBS will report the build results back to GitHub. @@ -1102,7 +1102,7 @@ test_build: - + Workflow Runs For every SCM event, OBS compiles relevant information about the workflows running on the system. You can find the @@ -1172,7 +1172,7 @@ test_build: the workflow run will record error messages. And reading the artifacts will help to understand what happened behind the scenes. - + Errors @@ -1225,7 +1225,7 @@ test_build:
- + Equivalence Table @@ -1282,7 +1282,7 @@ test_build: - + SCM/CI Workflow Steps Reference Table For each step, this table shows which event on the SCM will trigger which operations on the OBS. @@ -1510,7 +1510,7 @@ test_build:
- + SCM/CI Workflow Versions To secure the compatibility of SCM/CI workflows with new features and changes, we are introducing those through new versions. We specify them with a - + Workflow Version Table Current available workflow versions and the introduced changes can be found in the versions table below. @@ -1561,10 +1561,10 @@ test_build: - + SCM/CI Workflow Integration Use-Cases - + OBS SCM Service For some of the use cases, you might want the OBS package to get @@ -1578,7 +1578,7 @@ test_build: it. - + Test Build a Package For Every Pull Request on GitHub You decide to manage your package sources from a GitHub @@ -1586,7 +1586,7 @@ test_build: sources by opening a pull request, you need to verify that your package still builds for certain repositories and architectures in OBS. You can have the best of both worlds with the . + linkend="sec-obs-obs-scm-ci-workflow-integration-setup"/>. You will need: @@ -1612,24 +1612,24 @@ test_build: The required tokens to allow OBS and GitHub talk each other as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication"/> The required webhooks so GitHub notifies OBS of any event as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-webhooks"/> This is obviously a good candidate to use the . + linkend="sec-obs-obs-scm-ci-workflow-integration-use-cases-service"/>. There are two different strategies to do this: branching the package or linking to it. - + Branch If you decide to branch the package for the test build, the @@ -1658,12 +1658,12 @@ test_build: package will be deleted. Read and, + linkend="sec-obs-obs-scm-ci-workflow-integration-setup"/> and, specifically, the workflow steps (). + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-obs-workflows-steps"/>). - + Link and Configure Repositories If you prefer to link the package for the test build, the @@ -1704,13 +1704,13 @@ test_build: flexibility to decide which repositories are you interested in. Read and, + linkend="sec-obs-obs-scm-ci-workflow-integration-setup"/> and, specifically, the workflow steps (). + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-obs-workflows-steps"/>). - + Rebuild a Package for Every Change in a Branch You have a test build set up and you want it to keep up to date @@ -1733,18 +1733,18 @@ test_build: The required tokens to allow OBS and GitHub talk each other as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication"/> The required webhooks so GitHub notifies OBS of any event as explained in + linkend="sec-obs-obs-scm-ci-workflow-integration-setup-webhooks"/> The source code synchronization setup with the . + linkend="sec-obs-obs-scm-ci-workflow-integration-use-cases-service"/>. @@ -1759,7 +1759,7 @@ test_build: event: push - + Set Flags on a Package to Disable Builds for an Architecture When you branch a package, all its repositories and their architectures will be copied over. @@ -1784,7 +1784,7 @@ test_build: - + Create Package on OBS for Every Software Release With Git Tags You have a software project for which you mark releases with Git tags. For every release, you want to create @@ -1795,7 +1795,7 @@ test_build: versioned releases to another project on OBS if you need it as a dependency. After the usual setup for - OBS workflows with tokens and webhooks (see ), you will need: + OBS workflows with tokens and webhooks (see ), you will need: @@ -1894,7 +1894,7 @@ test_build: - + Using a Custom Configuration File URL in Combination with Placeholder Variables It may happen that you have multiple repositories following the same @@ -1934,14 +1934,14 @@ test_build: From here the only thing left to do would be to host this file somewhere where OBS can access it, creating a workflow token and the - corresponding webhooks (following the setup instructions at ) + corresponding webhooks (following the setup instructions at ) for every SCM repository you want this configuration file to apply to, - making sure you set the correct configuration url (see ). + making sure you set the correct configuration url (see ). There are many other ways to use these two features in parallel, make sure to read - - and + + and to get some inspiration on how you can use them in your project. diff --git a/xml/obs_signing.xml b/xml/obs_signing.xml index e6075b63..b974edb3 100644 --- a/xml/obs_signing.xml +++ b/xml/obs_signing.xml @@ -3,7 +3,7 @@ %entities; ]> - diff --git a/xml/obs_source_management.xml b/xml/obs_source_management.xml index 38389ea3..24ad302d 100644 --- a/xml/obs_source_management.xml +++ b/xml/obs_source_management.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -54,7 +54,7 @@ OBS 2.11 can produce and publish additional SPDX data for certain build types. This is controlled via the project configuration. For details, refer to - for + for sbom:FORMAT (under BuildFlags). diff --git a/xml/obs_source_service.xml b/xml/obs_source_service.xml index 19cedfa8..64e406b1 100644 --- a/xml/obs_source_service.xml +++ b/xml/obs_source_service.xml @@ -3,14 +3,14 @@ %entities; ]> - Using Source Services - + About Source Service Source Services are tools to validate, generate or modify sources in a @@ -81,7 +81,7 @@ For using source services you need (refer to ): + linkend="ex-obs-sserv-struct"/>): @@ -101,34 +101,34 @@ - + Structure of a <filename>_service</filename> File - <services> - <service name="MY_SCRIPT" mode="MODE"> - <param name="PARAMETER1">PARAMETER1_VALUE</param> + <services> + <service name="MY_SCRIPT" mode="MODE"> + <param name="PARAMETER1">PARAMETER1_VALUE</param> </service> </services> - + The root element of a _service file. - + The service name. The service is a script that is stored in the /usr/lib/obs/service directory. - + - Mode of the service, see . + Mode of the service, see . - + One or more parameters which are passed to the script defined in - . + . @@ -142,7 +142,7 @@ services from /usr/lib/obs/service/? - + Modes of Services Each service can be used in a mode defining when it should run and how to use the result. This can be done per package or globally for an @@ -192,7 +192,7 @@ buildtime - During each build before calling the build tool (for example, rpm-build) + During each build before calling the build tool (for example, rpm-build) A side effect is that the service package is becoming a build dependency and must be available. @@ -298,7 +298,7 @@ - + Defining Services for Validation Source Services can be used to validate sources. This can be defined @@ -351,7 +351,7 @@ - + Creating Source Service Definitions Source services are defined in the _service file @@ -397,7 +397,7 @@ - + Removing a Source Service Sometimes it is useful to continue working on generated files manually. In this situation the _service file needs @@ -408,16 +408,16 @@ osc service merge. - + Trigger a service run via a webhook You may want to update sources in &obs; whenever they change in a SCM system. You can create a token which allows to trigger a specific package update and use it via a webhook. It is recommended to create a token for a specific package and not a wildcard token. - Read to learn how to + Read to learn how to create a token. - + Using it on gitlab Go to your repository settings page in your gitlab instance. Select Integrations @@ -432,7 +432,7 @@ https://YOUR_INSTANCE/trigger/runservice?project=PROJECT&package=PACKAGE - + Using it on github.com Go to your repository settings page of your repository on github.com. Select Webhooks diff --git a/xml/obs_staging_workflow.xml b/xml/obs_staging_workflow.xml index 6a27ef5f..1cde3eae 100644 --- a/xml/obs_staging_workflow.xml +++ b/xml/obs_staging_workflow.xml @@ -4,12 +4,12 @@ %entities; ]> - Staging Workflow - + Working with Staging Projects This API provides an easy way to get information about a single or all staging projects like @@ -17,7 +17,7 @@ Note: To use this API, you first need to setup a staging workflow for a project. - + Overview of All Staging Projects This endpoint provides an overview of all staging projects for a certain project. @@ -79,7 +79,7 @@ geeko > osc api '/staging/openSUSE:Factory/staging_projects/? - + Overview of a Single Staging Project This endpoint provides an overview of a single staging project. @@ -122,7 +122,7 @@ geeko > osc api '/staging/openSUSE:Factory/staging_projects// - + Copy a Staging Project This endpoint creates a copy of a staging project. It will queue a job which is going to copy the project configuration, repositories, groups and users. @@ -133,11 +133,11 @@ geeko > osc api -X POST '/staging/openSUSE:Factory/staging_pr - + Working with Requests One of the main features of the staging workflow is assigning incoming requests to different staging projects. - + Assign Requests into a Staging Project Our main project openSUSE:Factory received requests with id 1 and 2. @@ -149,7 +149,7 @@ geeko > osc api -X POST '/staging/openSUSE:Factory/staging_pr - + Remove Requests from a Staging Project When we are done with testing the staging project openSUSE:Factory:Staging:A, we need to remove the requests 1 and 2 again. @@ -160,7 +160,7 @@ geeko > osc api -X DELETE '/staging/openSUSE:Factory/staging_ - + List Requests of a Staging Project Listing all requests which are currently assigned to openSUSE:Factory:Staging:A can be done with the following command. @@ -181,7 +181,7 @@ geeko > osc api '/staging/openSUSE:Factory/staging_projects/o - + Exclude Requests for a Staging Workflow Our main project openSUSE:Factory received requests with id 3 and 4. @@ -192,7 +192,7 @@ geeko > osc api -X POST '/staging/openSUSE:Factory/excluded_r - + Bring Back Excluded Requests from a Staging Workflow The following command will stop excluding requests with id 3 and 4 for the staging workflow project openSUSE:Factory. @@ -202,7 +202,7 @@ geeko > osc api -X DELETE '/staging/openSUSE:Factory/excluded - + Accept Staging Project Once all the requests are ready and the staging project has an acceptable state, the requests can be merged. In other words, the staging project can be accepted. diff --git a/xml/obs_supported_formats.xml b/xml/obs_supported_formats.xml index 567ab82a..6af38099 100644 --- a/xml/obs_supported_formats.xml +++ b/xml/obs_supported_formats.xml @@ -3,7 +3,7 @@ %entities; ]> - @@ -14,7 +14,7 @@ This chapter is focusing on describing &obs; specifics of a format. Either limitations or extensions of &obs; builds. - + Spec File Specials (RPM) To create an RPM package, you need a spec file. diff --git a/xml/obs_user_concept.xml b/xml/obs_user_concept.xml index 63c54012..dffbc796 100644 --- a/xml/obs_user_concept.xml +++ b/xml/obs_user_concept.xml @@ -4,7 +4,7 @@ %entities; ]> - diff --git a/xml/osc_building.xml b/xml/osc_building.xml index 161ee152..aee4b590 100644 --- a/xml/osc_building.xml +++ b/xml/osc_building.xml @@ -4,7 +4,7 @@ %entities; ]> - @@ -21,7 +21,7 @@ toms 2017-08-18: Also integrate content from obs_build_containers.xml - + Generic build options Independent of the build format you need at least one source file as build description. @@ -55,7 +55,7 @@ If you have not done so yet, set up your project as shown in - . + . @@ -141,7 +141,7 @@ The buildroot was: /var/tmp/build-root/openSUSE_Tumbleweed-x86_64 - + Advanced Build Environment Handling The default build environment for local builds is usually chroot. While this is simplest environment