SUMA product docs IBS

Packaging internal build service docs (SUMA)

Table of Contents

• Building SUMA packages with the uyuni-docs-helper
  • Requirements
  • Configuring parameters for IBS
    • Remote Build
    • Local Build
  • Build the packages
  • Set the OBS Environment Variables
  • Package change entries
    • The Manager 4.2 Changelog entries
    • The Manager 4.3 Changelog entry
  • Check in the Changes

Building SUMA packages with the uyuni-docs-helper

Requirements

• You have uyuni-docs-helper container set up, see uyuni-docs-helper

• You have the SUSE Open build service tools set up on your local machine, see The OBS Tutorial

• You have an internal account at build.suse.de and you are logged in

• You also must have secondary authentication set up, see Multi-Factor Authentication (MFA)

Configuring parameters for IBS

Remote Build

For a remote build, you need to adjust the parameters.yml file for your target (RPM product docs).

If you are using the uyuni-docs-helper image to build from the remote source, make the following example changes to your local uyuni-docs/ checkout and then push them to the remote repository on GitHub. Then follow the remote build commands below.

Local Build

If you are using the uyuni-docs-helper image to build from your local git checkout, modify the local parameters.yml file and then follow the local build commands below.

1. Ensure you are on the correct branch, then open parameters.yml in your editor of choice. For the WebUI the url value should be set to /

   ⚠️	While working on the parameters file make sure that you adjust the SUMA section and not the Uyuni section.

   Example

       site:
         - attribute: title
           value: "SUSE Manager Documentation"
         - attribute: start_page
           value: "suse-manager::index"
         - attribute: url
           value: /

2. Check the following block in parameters.yml ensuring the version numbers are correct. The yaml or attributes themselves should not be adjusted. Only the version numbers should be adjusted:

   Example

     suma:
       asciidoc:
         - attribute: productnumber
           value: "4.3"
         - attribute: docversion
           value: "4.3"
         - attribute: minorversion
           value: "4.3.5"
         - attribute: saltversion
           value: 3004
         - attribute: sles-version
           value: 15
         - attribute:  sp-version
           value: SP4
         - attribute: smrproductnumber
           value: 4.2
         - attribute: opensuse-version
           value: 15.4

3. Add the correct supplemental_files value for the SUMA WebUI theme:

         supplemental_files: ./branding/supplemental-ui/suma/webui-2023

4. Push your changes to the remote repository release branch.

Build the packages

There are two methods to build the packages from the uyuni-docs-helper directory. You can build either from a remote source or a local repository clone. Select one of the following two methods:

Remote build

The following command builds the docs from the remote repository.

Example

./uyuni-docs-helper -r manager-x.y-MU-x.y.z -o ./tmp -c obs-packages-suma-en -p suma

Local build

The following command builds the docs from the local uyuni-docs checkout:

Example

./uyuni-docs-helper -l ../uyuni-docs -r manager-x.y-MU-x.y.z -c obs-packages-suma-en -p suma

Set the OBS Environment Variables

1. Once the packages are built configure your environment variables for OBS on the CLI:

   Example

   OBS_USER=jcayouette
   OBS_USER=keichwa
   OBS_USER=omaric

2. Add the target project repository.

   Example

   OBS_REPO=Devel:Galaxy:Manager:4.2      # Maintained major release
   OBS_REPO=Devel:Galaxy:Manager:4.3      # Latest major release
   OBS_REPO=Devel:Galaxy:Manager:Head     # Alpha and beta releases

3. Check out the docs package from OBS:

   For SUSE Manager:

   osc -A https://api.suse.de bco $OBS_REPO susemanager-docs_en

   💡	If this fails with a 404, go to the build.suse.de site and log in, then try again.

4. Find and copy the two new English packages located in your build output directory: /build/packages` into:

   home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en*

Package change entries

You need to update the changes files using our changelog at uyuni-docs/changelog.

Manager 4.2 and Manager 4.3 both use slightly different changelog update methods.

The Manager 4.2 Changelog entries

1. Change into the OBS checkout dir:

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

2. Your changes need to be duplicated in the two following files (including date and time):

   • susemanager-docs_en.changes

   • susemanager-doc-indexes.changes

3. Edit the first file:

   osc vc susemanager-docs_en.changes

4. Copy the changes from the .changelog file including the timestamp with user and email, and save. It should look something like this:

   susemanager-docs_en.changes

   -------------------------------------------------------------------
   Wed Jun 19 15:16:07 UTC 2019 - <FIRSTNAME> <LASTNAME> <USER-EMAIL@suse.com>
   
   - 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)
   
   -------------------------------------------------------------------

5. Use an exact copy of the first entry for the second file:

   osc vc susemanager-doc-indexes.changes

   ⚠️	Make sure the changes are exactly the same! The changes files must be located in the home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en directory, along with the new package files you created earlier. If the files are different, they will be rejected by the release manager.

6. Save the file and proceed to Check in the Changes.

The Manager 4.3 Changelog entry

From Manager 4.3 and onward the changelog entries have been simplified. You no longer need to dupilicate both index and docs_en files.

1. Change into the OBS checkout dir:

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

2. Add the latest changes from the uyuni-docs/changelog by running:

    osc vc susemanager-docs_en.changes

3. It should look something like this:

   susemanager-docs_en.changes

   -------------------------------------------------------------------
   Wed Jun 19 15:16:07 UTC 2019 - <FIRSTNAME> <LASTNAME> <USER-EMAIL@suse.com>
   
   - 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)
   
   -------------------------------------------------------------------

4. Save the file and proceed to Check in the Changes.

Check in the Changes

1. Check in the changes. This will also initiate the build:

   osc ci -m "update"

2. 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

3. Once you are certain doc packages are building properly on OBS submit an service request to @susemanager-releng on slack. If everything looks good they will accept your service request and the docs will be included in the new RPM’s.

   osc sr -m 'update'

This concludes submitting doc packages on IBS.

Next, see Publishing to documentation.suse.com.

For more topics on building documentation, see Building documentation.