Jump to: navigation, search

Requirements

Adding a Requirement to an OpenStack Project

In order to add or change a Python dependency requirement of an OpenStack project, it must first be added to the openstack/requirements repository.

The process for that is maintained in the README.rst of the requirements repository.

Requirements Team

Changes to openstack/requirements are approved by the requirements-core team in Gerrit. If you have an interest in coordinating dependency package versions across all the OpenStack projects and vetting new dependencies for their suitability for inclusion, please start reviewing changes to openstack/requirements. As your gain experience and your reviews are found helpful, you may be asked to join the core team.

Review Criteria

Consider the following criteria when reviewing changes to openstack/requirements

  • license compatible (Apache2, MIT, BSD are probably okay, Copyleft licenses may be okay depending on circumstances)
  • license included in a trailing comment on the same line as version spec
  • python3 compatibility (all new requirements should be python3 compatible)
  • active development
  • prefer items already packaged in distros
  • project has api compat commitment/policy
  • apply the same considerations to transitive dependencies
  • commit log message includes reasoning for update
  • commit log message includes information about the OpenStack project(s) using the requirement
  • do the new versions overlap with previous versions to allow for CI/CD? (http://lists.openstack.org/pipermail/openstack-dev/2014-February/026898.html)

Additionally, regarding upstream version

  • minor upstream version updates should be considered routine/cursory review
  • use of pre-release versions of things needs an explanation
  • requirements with a missing upper bound on < next major number are dangerous

Upper Version Bounds

See here for an example of the kind of considerations needed when deciding which upper version bound best reflects the project's API compat policy:

python-seamicroclient>=0.1.0 # you *never* plan to break the API
python-seamicroclient>=0.1.0,<0.2 # you plan to break the API during the 0.x series, but may release compatible 0.1.x releases
python-seamicroclient>=0.1.0,<1 # you plan to maintain API compat until you release 1.0 with breaking changes
python-seamicroclient>=0.1.0,<2 # you plan to maintain API compat even in 1.0, but will move to 2.x if you make API changes

Setting up a project to receive the requirements updates

The first step is to submit a patch to the file "zuul/layout.yaml" and ensure that your project has a "check-requirements" job template listed, like e.g.

- name: openstack/yourproject
   template:
     - name: check-requirements
    ....

This step adds a CI job to your review process, when the requirements.txt in your project differs from the one in global-requirements.txt it will complain loudly and fail your review. This ensures that your project requirements.txt will not have anything other than the entries in global-requirements.txt

The next step is to submit a patch to this file requirements/projects.txt. This ensures that when the nightly proposal bot/script runs, it will create a fresh review in your project queue with any changes that were made to global-requirements.txt.

We won't accept a patch for projects.txt without seeing a review for for the first step.

Contact

The team can be found on the Freenode IRC channel #openstack-requirements.

Preferred way to interact with the contributors or notify the requirements team about issues with the global requirements is to join the IRC channel and just start collaborating. The requirements team is about to setup a weekly IRC meeting.