Skip to content

SUMA product docs IBS

Jump to bottom
Karl Eichwalder edited this page May 22, 2024 · 19 revisions

Packaging internal build service docs (SUMA)

Building SUMA packages with the uyuni-docs-helper

Requirements

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 susemanager-docs_en 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 file using our changelog at uyuni-docs/.changelog.

Manager 4.3 uses slightly different changelog update methods compared to older version Manager 4.2.

The Manager 4.3 Changelog entry

  1. Change into the OBS checkout directory:

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

  2. In the .spec file set Version: to the release version. For example:

    Name:           susemanager-docs_en
Version:        4.3.9
Release:        0

  3. Add the latest changes from uyuni-docs/.changelog and the release version number by running:

     osc vc susemanager-docs_en.changes

  4. It should look something like this:

    susemanager-docs_en.changes
    -------------------------------------------------------------------
Wed Jun 19 15:16:07 UTC 2019 - <FIRSTNAME> <LASTNAME> <[email protected]>

- Version 4.3.9
  - 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. 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 progress of the build (project results) with:

    osc pr

Create the Service Request (or supersede the existing one)

  1. When the new Service Request needs to be created, or when the new one needs to supersede the existing SR, run the command below. Make sure you answer the question Supersede the old request? (y/n/c) adequately:

    osc sr -m 'update'

  2. Once you are certain doc packages are built properly on OBS, inform @susemanager-releng on Slack about the SR.

  3. If everything looks good, release manager will accept the service request and the docs will be included in the new RPMs.

This concludes submitting doc packages on IBS.

Navigation

  1. Previous: SUMA GitHub actions update

  2. Next: Publishing to documentation.suse.com

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

uyuni logo

Uyuni Docs

Clone this wiki locally