Using an Oslo Library

Oslo libraries participate in the same integrated gate as the rest of the OpenStack projects. They also support integration at the unit test level, so that unreleased changes to libraries do not break unit tests of consuming applications. This page explains how to set up a project to use a library and introduce the gate jobs, without blocking changes from the application.

Ensure the Library is Ready

Check that the library is present in the list of released libraries in Oslo#Libraries. If not, talk to the Oslo team about whether or not it is ready to be used. Some library repositories may exist for an extended time while the library is graduating and before the library is released and ready to be used.

Check the Documentation

Refer to the migration notes linked under Oslo#Libraries for the library you are working with to learn what sort of changes are needed.

Create Unit Test Cross-test Jobs

These changes should be submitted as one patch to openstack-infra/config. Replace "project" in names with the name of your project and "libname" with the name of the library being added.

Add Cross-test Jobs to Your Project

Edit modules/openstack_project/files/jenkins_job_builder/config/projects.yaml to add "libname-cross-test" to the job list for your project.

- project:
   name: project-name
   github-org: openstack
   node: precise
   tarball-site: tarballs.openstack.org
   doc-publisher-site: docs.openstack.org
   jobs:
     - python-jobs
     - openstack-publish-jobs
     - pypi-jobs
     - integrated-gate
     - libname-cross-test

Configure Zuul for the New Jobs

Edit modules/openstack_project/files/zuul/layout.yaml to add "check-libname-dsvm-project" and "gate-libname-dsvm-project" to the list of jobs for your project:

 - name: openstack/project
   template:
     - name: python-jobs
     - name: openstack-server-publish-jobs
     - name: check-requirements
     - name: integrated-gate
   check:
     - check-libname-dsvm-project
   gate:
     - gate-libname-dsvm-project

Optionally set those jobs non-voting by adding a block to the "jobs" list at the top of the file (look for "voting: false" and add an entry to the bottom of the list):

 - name: ^(gate|check)-libname-dsvm-project
   voting: false

Wait for this change to be approved by the infra team before proceeding.

Add the Library to Your Requirements

Update the requirements.txt file in your project with the library's entry from the global-requirements.txt file in the openstack/requirements project. Frequently this will be just the name of the library, but sometimes a minimum version is specified.

 libname>=1.2.0

Submitting this change will trigger the jobs added in the previous step. Verify that they pass, even if they are non-voting, before proceeding.

Modify the Code in Your Project

Following the migration instructions provided for the library, update your application to use the library.

If you are using a library recently graduated from the incubator, remove the incubated version of the code from your application at the same time to ensure that all modules are using the new library. You may have to sync other modules from the incubator to update their references to the graduated code.
Update the dependency list for your project to remove any items brought in by the Oslo library. This will make it easier to manage requirements, since eventually only one OpenStack project will have the version specified.

This is likely to be a large commit, so you will want to give the core reviewers on your project advance notice that you are starting the work so the review can be scheduled and prioritized appropriately.

Make Cross-test Jobs Voting

If you set up the unit test jobs as non-voting earlier, update them so they are voting by removing the entry from the "jobs" list at the top of the file.

Wait for this change to be approved by the infra team before proceeding.

Establish Cross-test Jobs for the Library on Your Project

Edit modules/openstack_project/files/zuul/layout.yaml to add "check-libname-dsvm-project" and "gate-libname-dsvm-project" to the list of jobs for the library:

 - name: openstack/libname
   check:
     - check-libname-dsvm-project
   gate:
     - gate-libname-dsvm-project

This will cause zuul to run those jobs for changes to the library, ensuring that nothing is checked into the library that will break the unit tests in your application.

Oslo/UsingALibrary

Contents