Building Uyuni docs for the Open Build Service

Building Uyuni Docs

Table of Contents

• Building UYUNI OBS packages
  • Requirements
  • WEBUI playbook files (UYUNI)
  • Build the packages
• Navigation

Building UYUNI OBS packages

Requirements

• You have uyuni-docs-helper container set up, see *https://github.com/uyuni-project/uyuni-docs-helper/blob/main/README.md[uyuni-docs-helper]

• You have access to build.opensuse.org

WEBUI playbook files (UYUNI)

1. From your local git checkout of uyuni-docs in parameters.yml verify that the default value for site.url is enabled for uyuni-project.org.

   site:
         - attribute: title
           value: "Uyuni Documentation"
         - attribute: start_page
           value: "uyuni::index"
         - attribute: url
           value: https://www.uyuni-project.org/uyuni-docs/

2. Check the Uyuni version number in the parameters.yml. This should be adjusted to the release version.

       asciidoc:
         - attribute: productname
           value: "Uyuni"
         - attribute: productnumber
           value: "2024.01"
         - attribute: docversion
           value: "2024.01"
         - attribute: minorversion
           value: "2024.01"

3. Check the following attributes in the parameters.yml ensuring the file version numbers are correct. These numbers can be found in the OBS package spec files. For example: salt.spec:

   asciidoc:
     - attribute: opensuse-version
       value: 15.5
     - attribute: saltversion
       value: 3006.0
     - attribute: postgresql
       value: PostgreSQL
     - attribute: postgresql-version
       value: 14 // for Uyuni. For SUMA it is 16 - confirm this!
     - attribute: sles-version
       value: 15
     - attribute:  sp-version
       value: SP5 #use for normal text
     - attribute: sp-vert
       value: sp5 #use for terminal block
     - attribute: sp-version-l
       value: sp5

Build the packages

1. Build the OBS packages. From the local checkout directory on the command line, run:

   example

   make obs-packages-uyuni

2. Once packages are built, configure the correct environment variables for OBS:

   example

   OBS_USER=keichwa
   OBS_USER=jcayouette
   OBS_USER=omaric

3. Add the target OBS repo. For Uyuni, use:

   example

   OBS_REPO=systemsmanagement:Uyuni:Master

4. Checkout the document package from OBS:

   osc -A https://api.opensuse.org bco $OBS_REPO uyuni-docs_en

   If this fails with a 404, login to your account at build.opensuse.org and try again.

5. Copy the two new packages located in build/packages into:

   build/home:$OBS_USER:branches:$OBS_REPO/uyuni-docs_en

6. Change into the OBS checkout dir:

   cd home:$OBS_USER:branches:$OBS_REPO/uyuni-docs_en

7. Update the changes file.

   For Uyuni, it is named:

   • uyuni-docs_en.changes

     osc vc uyuni-docs_en.changes

8. Copy the latest changes from CHANGELOG.md in the uyuni-docs repo. Paste the changes under the timestamp, and update and adjust for correct line length and spelling. Try not to use acronyms. The release number should be the topmost entry in this file and must be bumped for each new release. It should look something like this:

   example

   -------------------------------------------------------------------
   Wed December 19 15:16:07 UTC 2023 - FirstName LastName <[email protected]>
   
   - Version 2024.01   <---- BUMP VERSION
    * Updated wording for prometheus section
    * Jeos VM update
    * Port 8050 for graphical console display
    * Content life-cycle docs are not enough for customer to understand
      (bsc#1137955)
    * Salt boot formula fails for SLES11 SP3 terminal (bsc#1136857)
    * Certificate verify failed when using vmware esxi virtual host gatherer
      (bsc#1136561)
   
   -------------------------------------------------------------------

The changes file must be located in the build/home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en directory, along with the package files you created earlier.

1. For Uyuni, you need to update the version release number in the .spec files. Open the following file in your text editor, and update the Version: entry (around L19) with the version you are preparing:

   • uyuni-docs_en.spec

     example

     Name:           uyuni-docs_en
     Version:        2024.01
     Release:        0

     Save the files.

2. Check in the changes. This will also start the build:

   osc ci -m "update"

3. It will take about 15 minutes for all the packages to build. You can check the build results in your home project; e.g. with:

   osc pr

   Alternatively, you can go to the OBS site to monitor progress.

4. When you are certain that document packages are built properly on OBS, submit a service request to @rel-engineers on Slack:

   osc sr -m 'update'

   After a successful review, they will accept the service request (SR).

Navigation

1. Previous: Uyuni GitHub actions update

2. Next: Publishing to uyuni-project.org

3. Up: For more topics on building documentation, see Building documentation