Oslo/UsingALibrary
Contents
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. You may have to sync other modules from the incubator to update their references to the graduated code.
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.