oVirt UI Extensions

Introduction

This project contains UI plugins that provides various extensions to oVirt administration UI.

This extension is installed during oVirt Engine installation and upgraded via engine-setup. This means no manual steps are required in order to install this extension in an production environment.

Setting up development environment

Prerequisites

• Install Node.js (LTS). nvm can be used to manage multiple Node.js versions. Run node -v to check the current Node.js version.

• Install Yarn package manager.

• Build and configure oVirt Engine according to its developer instructions.

• Checkout the sources from GitHub.

Note	Required versions of nodejs and yarn can be seen in the current rpm spec template.

Setting up the extension

• yarn install to install dependencies

• yarn lint to lint the source code

• yarn test to run tests (single run)

• yarn test:watch for continuous testing (watch & rerun tests on change)

• yarn dev for development build

• yarn dev:watch for continuous development (watch & rebuild on change)

• yarn build for production build

Setting up Engine

Build the extension with yarn dev or yarn build to generate ${PLUGIN_REPO}/dist.

Symlink the extension’s plugin resources to ui-plugins directory of your developer engine as follows:

 % cd ${PREFIX}/share/ovirt-engine/ui-plugins/
 % ln -s ${PLUGIN_REPO}/dist/ui-extensions.json ui-extensions.json
 % ln -s ${PLUGIN_REPO}/dist/ui-extensions-resources ui-extensions-resources

Symlink the extensions’s ansible resources to playbooks directory of your developer engine as follows:

 % cd ${PREFIX}/share/ovirt-engine/ansible-runner-service-project/project
 % ln -s ${PLUGIN_REPO}/ansible-playbooks/*

Note	If you add additional playbook yml files after the initial symlink, the process will need to be repeated.

Accessing the plugins

Open WebAdmin in your browser, you should land on Dashboard place automatically:

https://engine.example:8443/ovirt-engine/webadmin/

Internationalization and Localization

Introduction

This project has the ability to render in different languages. Internally, all of the localizable keys are stored in src/intl/messages.js. The msg object in intl-messages.js wraps all of the localizable keys to expose them as functions. The msg object also wraps all of the localized translations loaded from src/intl/translations.json and uses a localized version of each key as required.

The current locale used by the intl.js formatting functions is provided to the application via the app-init.js service and the oVirt UI plugin API.

We use the Zanata tool instance to manage translations.

Translation workflow

Generally, the project is made localizable and is translated in the following workflow:

• Developers add messages as needed to src/intl/messages.js

• Developers then import from intl-messages.js and use the msg object to both access and format the messages

• When the strings are stable, the messages are converted to a GNU gettext .pot file

• The .pot file is pushed to Zanata

• Translators do their work for each supported language within the corresponding Zanata project

• When translations are complete, the localized strings are pulled from Zanata as a set of GNU gettext .po files

• The .po files are converted to a JSON file, specifically src/intl/translations.json

• The JSON file is referenced in intl.js, providing localized messages to the msg object in intl-messages.js

• Rebuilding the project will make the updated translations available for use

Zanata setup

Setup your Zanata configurations in the usual way. See Zanata client setup documentation for details.

Commands

Push current English source strings to Zanata

Pushing the current English sources will update the project on Zanata. Any strings that have been added, changed or deleted will be shown as such in the Zanata UI. Here is the set of commands to push the changes:

% yarn intl:extract
% yarn intl:push

Pull updated translations from Zanata

To properly pull and update from Zanata, the source JSON and POT files must exist. This is done by running the intl:extract script. Standard zanata CLI pulls the data down as PO files. The PO files get converted into a single JSON file containing translations for all locales. This JSON file needs to be normalized for git diff sanity.

% yarn intl:extract
% yarn intl:pull
% yarn intl:apply
% yarn intl:normalize

Instructions for maintainers

Managing dependencies

Dependencies not related to production build (not needed for yarn build) should go into devDependencies. Try to keep as few dependencies as possible.

Whenever dependencies are changed, they need to be pre-seeded to ovirt-engine-nodejs-modules for CI to pass offline builds.

Package versioning

• alpha and beta builds (pre-releases): x.y.z-0.N where version stays the same

• RC and GA builds (releases): x.y.z-N where version grows between releases

version in package.json is reflected into the RPM x.y.z version.

Release process

Only covers release builds (RC and GA).

Stable branches

To create new stable branch:

1. create new branch on the GitHub repo

2. rebase on top of the newly created branch

Then, update the master branch:

• submit pull request with following changes:

  • package.json - bump version

  • packaging/spec.in - reset Release number to 1 and update %changelog

TODO: Do any changes need to be made to copr, for builds, or a github actions, for CI, if a new stable branch is added?

Releases

To perform new release:

1. switch to appropriate stable branch

2. submit pull request that prepares the branch for release:

   1. package.json - ensure proper version (e.g. bump .z component)

   2. packaging/spec.in - ensure proper Release number and update %changelog

3. pull changes from remote

4. tag release-prep patch and push the tag to remote:

   1. git tag -a <tag-name>

   2. git push origin <tag-name>

5. trigger CI build on release-prep patch

6. update oVirt release config in releng-tools repo

Tag name example: ovirt-engine-ui-extensions-1.0.0-1

Building RPM

GitHub pull request

GitHub actions that run CI on each pull request do a full rpm build. To access the RPMs for a pull request, open the checks tab. If the offline / ovirt-engine-nodejs-modules check passed, the artifacts should be available on that page or on the action run’s page.

Manual build

Alternatively, a RPM can be built locally using the packaging/build.sh script. To build online (skipping ovirt-engine-nodejs-modules), you will need to install the packages listed in the packaging/spec.in file BuildRequires lines. As of 2022-Feb-15, install:

  % sudo dnf install git jq rpmlit rpm-build yarn nodejs

Then build with the command:

  % OFFLINE_BUILD=0 ./packaging/build.sh

Upon a successful build, the RPMs will be located in the exported-artifacts/ folder.