From Mageia wiki
Revision as of 00:24, 17 November 2018 by Martinw (talk | contribs) (Added installation section and details about downgrading packages after testing and additional error checks)
Jump to: navigation, search


Introduction

When testing an update, the recommended procedure is to only install the packages listed in the update request. This is because those are the only packages that will be pushed to the updates media when the update has been validated.

If a tester enables the updates_testing media and manually selects the packages to be updated, there is the chance that other packages present in updates_testing will get automatically installed (due to package dependencies). Most of the time this causes no problems, but if the update actually requires some of those additional packages, users will experience problems once the update is pushed, because those additional packages won't necessarily be available in the updates media.

To help avoid such problems, the QA Repo tool was created. This tool takes a list of packages supplied by the tester and creates a local repository on the tester's machine containing just those packages. It then enables that repository as an update medium, so that when the tester runs the software update GUI (or urpmi –auto-select), those packages will be available as updates. Provided the tester never enables the updates_testing media, there is no danger that other packages in updates_testing will get installed.

To completely avoid problems, the updated packages need to be downgraded again before moving on to testing another update request. Currently this still needs to be done manually, but the QA Repo tool can suggest a command to run to achieve this. If you are testing in a virtual machine, you can instead use clones or snapshots to enable you to roll back the changes.

Installation

The QA Repo tool may be installed in the tester's system by installing the qarepo package. Note that if testing in a virtual machine, the package needs to be installed in the guest system.

Most of the time the QA Repo tool runs without special privileges, but to enable or disable the local repository as an update medium it requires root privileges. It will only request these privileges when it needs them, using polkit to perform authentication (i.e. the authentication dialogue you see when running other programs that require root privileges, such as the MCC).

Because the polkit authentication expires after only a few minutes, you may choose to add yourself to the qarepo group (via the user management tool in the MCC or the usermod command). This will cause polkit to automatically authorise the QA Repo tool to perform the actions it needs to without you needing to enter a password, providing the tool is being run by you as an active local user.

Note:
For Mageia 6, the qarepo package is available in core/backports. For Mageia 7 and beyond, it will be available in core/release.

Instructions for use

The QA Repo tool may be started either by selecting it from the Tools section of the desktop applications menu or by entering qarepo on the command line. If run from the command line, you will see the output from the commands the QA Repo tool runs to create the local repository, which may be helpful to diagnose faults if it doesn't do what you expect it to.

Once started, you will be presented with the following GUI interface:

Qarepo.png

Selecting a mirror

On the first row of the GUI there is a text entry box that allows you to enter the URL of the mirror you wish to use for downloading packages. This may be a http://, ftp://, or rsync:// URL, or a simple file path (i.e. without the file:// prefix) to a mirror on your local filesystem. In all cases this should point to the top level of the distribution tree (the directory containing the distrib subdirectory).

Selecting the source media

On the second row of the GUI there is a text entry box that allows you to enter the Mageia release number you wish to test and tick boxes to select which of the media types are enabled (the core media are always enabled). On the third row there is a drop down list that allows you to select which architecture you are testing (either i586 or x86_64).

The QA Repo tool will only download packages from the updates_testing sections of the selected media.

Selecting the location of the local repository

On the third row of the GUI there is a text entry box that allows you to specify the location of the directory that will be used to store the local repository created by the QA Repo tool. This should be an absolute path on your local filesystem. The directory will be created if it doesn't already exist. The local repository will be created as a subdirectory of this directory, named after the selected architecture.

Selecting the packages to be tested

On the fourth row of the GUI there is a text entry box that allows you to select which packages are to be downloaded and stored in the local repository. It is recommended that you copy and paste the list of RPM names from the update request in Bugzilla. The packager who requested the update should have provided a complete list for each architecture, as stated in the Mageia Updates Policy.

If testing within a VirtualBox guest, it is helpful to set it to use a bidirectional clipboard. That will let you bring up the bug in the host's browser, copy the package list from the bug, and paste it into the guest's QA Repo.

Synchronising and enabling the local repository

When you make any changes to the above selections, the Enable button in the GUI will be changed into a Update button and the status line below the package selection box will show Needs update. This indicates the local repository does not currently contain the packages you have selected. Click on the Update button to start downloading the requested packages from the selected mirror. If successful, the Update button will be changed back to a (greyed-out) Enable button and the status line will show Enabled. Your local repository is now enabled and you can start installing the updates and testing.

If you run the software media manager (or urpmq –list-media) you will see your local repository appear as either QA Testing (32-bit) or QA Testing (64-bit), depending on the architecture you have selected. There are no sub-media within the local repository – all selected packages will be contained in a single medium, regardless of which media they were downloaded from.

If the synchronisation fails, a pop-up dialogue showing the reason for failure is displayed and the status line will show Update failed. Try to correct the problem (e.g. a mis-typed package name) and click on the Update button to try again.

The Clear button provides a quick way to clear the package selection box before pasting in a new list of packages. Note that it only clears the text entry box – the local repository remains unchanged until you click on the Update button.

Whenever you click on the Update button, any packages not currently listed in the package selection box will be removed from the local repository.

Disabling the local repository

Once the local repository is enabled, the Disable button will no longer be greyed-out. Clicking on the Disable button will disable and remove your local repository from the list of known software media and the status line below the package selection box will show Disabled. The local repository will, however, remain intact, and can be enabled again by clicking on the Enable button.

Downgrading packages after testing

Once you have finished testing a particular update, you will want to roll back the changes you have made to your test system so they don't affect subsequent tests. Clicking on the Downgrade button will bring up a pop-up dialogue showing a command you can run to automatically downgrade any packages currently listed in the package selection box that have been installed on your system. It will also automatically disable your local repository if you haven't done so already.

The downgrade will replace the listed packages with the latest version available in your currently enabled urpmi media. Do check the list of packages urpmi reports it is about to replace, just to make sure it isn't doing something it shouldn't.

Dual architecture testing

Occasionally you may wish to simultaneously test both 32-bit and 64-bit packages. To do this, first select the i586 architecture and create and enable a local repository for the 32-bit packages. Then select the x86_64 architecture and create and enable a local repository for the 64-bit packages. If you run the software media manager (or urpmq –list-media) you will then see both QA Testing (32-bit) and QA Testing (64-bit) listed.

You may freely switch between architectures in the QA Repo tool. It will always reflect the state of the repository for the currently selected architecture.

Don't forget to disable the repository for both architectures when you have finished testing.

Additional checks

If you have any updates_testing media enabled when you click on the Enable, Update, or Download buttons, a pop-up dialogue is displayed, asking you to disable those media before trying again.

Saved settings

Apart from the list of packages, all the selections described above will be saved in the ~/.qareporc file when you quit the QA Repo tool and restored when you next start it. On restart, if your local repository already exists (even if it is disabled), the package selection box will be populated with the current contents of the repository.

Non-standard use

When a major update is being prepared (such as the big Plasma update for Mageia 6), there may be a period where the list of packages to be tested is continually changing (as bugs are found and fixed), and there is no definitive list in Bugzilla. To aid testing in these circumstances, the following additional features are supported:

1. Package names may contain simple wildcards (? and *), which allows groups of similarly named packages to be selected with one entry in the package selection box.

2. The fuzzy version option may be enabled, which automatically replaces the version number in a package name with a wildcard.

3. The add deps option may be enabled, which automatically adds any package dependencies that can be found in the updates_testing media.

None of these features should be used during final testing and validation of an update request, as they defeat the main purpose of the QA Repo tool.