{ "info": { "author": "OpenStack", "author_email": "openstack-dev@lists.openstack.org", "bugtrack_url": null, "classifiers": [ "Environment :: OpenStack", "Intended Audience :: Information Technology", "Intended Audience :: System Administrators", "License :: OSI Approved :: Apache Software License", "Operating System :: MacOS :: MacOS X", "Operating System :: Microsoft :: Windows", "Operating System :: POSIX :: Linux", "Programming Language :: Python", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5" ], "description": "========================\nTeam and repository tags\n========================\n\n.. image:: https://governance.openstack.org/tc/badges/requirements.svg\n :target: https://governance.openstack.org/tc/reference/tags/index.html\n\n.. Change things from this point on\n\n============================================\n Global Requirements for OpenStack Projects\n============================================\n\nWhy Global Requirements?\n========================\n\nDuring the Havana release cycle we kept running into coherency issues\nwith trying to install all the OpenStack components into a single\nenvironment. The issue is that syncing of ``requirements.txt`` between\nprojects was an eventually consistent problem. Some projects would\nupdate quickly, others would not. We'd never have the same versions\nspecified as requirements between packages.\n\nBecause of the way that python package installation with pip works,\nthis means that if you get lucky you'll end up with a working\nsystem. If you don't you can easily break all of OpenStack on a\nrequirements update.\n\nAn example of how bad this had gotten is that python-keystoneclient\nwould typically be installed / uninstalled 6 times during the course\nof a DevStack gate run during Havana. If the last version of python\nkeystoneclient happened to be incompatible with some piece of\nOpenStack a very hard to diagnose break occurs.\n\nWe also had an issue with projects adding dependencies of python\nlibraries without thinking through the long term implications of those\nlibraries. Is the library actively maintained? Is the library of a\ncompatible license? Does the library duplicate the function of existing\nlibraries that we already have in requirements? Is the library python\n3 compatible? Is the library something that already exists in Linux\nDistros that we target (Ubuntu / Fedora). The answer to many of these\nquestions was no.\n\nGlobal requirements gives us a single place where we can evaluate\nthese things so that we can make a global decision for OpenStack on\nthe suitability of the library.\n\nSince Havana we've also observed significant CI disruption occurring due to\nupstream releases of software that are incompatible (whether in small\nor large ways) with OpenStack. So Global Requirements also serves as a control\npoint to determine the precise versions of dependencies that will be used\nduring CI.\n\nSolution\n========\n\nThe mechanics of the solution are relatively simple. We maintain a\ncentral list of all the requirements (``global-requirements.txt``)\nthat are allowed in OpenStack projects. This is enforced for\n``requirements.txt``, ``test-requirements.txt``,\n``doc/requirements.txt``, and extras defined in\n``setup.cfg``. This is maintained by hand, with changes going through CI.\n\nWe also maintain a compiled list of the exact versions, including transitive\ndependencies, of packages that are known to work in the OpenStack CI system.\nThis is maintained via an automated process that calculates the list and\nproposes a change back to this repository. A consequence of this is that\nnew releases of OpenStack libraries are not immediately used: they have to\npass through this automated process before we can benefit from (or be harmed\nby) them.\n\nFormat\n------\n\n``global-requirements.txt`` supports a subset of pip requirement file\ncontents. Distributions may only be referenced by name, not URL. Options\n(such as -e or -f) may not be used. Version specifiers, environment markers\nand comments are all permitted. A single distribution may be listed more than\nonce if different specifiers are required with different markers - for\ninstance, if a dependency has dropped Python 2.7 support.\n\n``upper-constraints.txt`` is machine generated and nothing more or less than\nan exact list of versions.\n\nEnforcement for Test Runs\n-------------------------\n\nDevStack\n++++++++\n\nDevStack uses the pip ``-c`` option to pin all the libraries to known good\nversions. ``edit-constraints`` can be used to unpin a single constraint, and\nthis is done to install libraries from git.\n\nTox\n+++\n\nWe are working on the necessary changes to use ``upper-constraints.txt`` in\ntox jobs but it is not yet complete.\n\nEnforcement in Projects\n-----------------------\n\nAll projects that have accepted the requirements contract (as listed\nin ``projects.txt``) are expected to run a requirements compatibility\njob. This job ensures that a project can not change any dependencies to\nversions not compatible with ``global-requirements.txt``. It also ensures that\nthose projects can not add a requirement that is not already in\n``global-requirements.txt``. This ``check-requirements`` job should\nbe merged in infra before proposing the change to ``projects.txt`` in\n``openstack/requirements``.\n\nAutomatic Sync of Accepted Requirements\n---------------------------------------\n\nIf an updated requirement is proposed to OpenStack and accepted to\n``global-requirements.txt``, the system then also automatically pushes\na review request for the new requirements definition to the projects\nthat include it.\n\nFor instance: if a review is accepted to ``global-requirements.txt``\nthat increases the minimum version of python-keystoneclient, the\nsystem will submit patches to all the OpenStack projects that list\npython-keystoneclient as a requirement or test requirement to match\nthis new version definition.\n\nThis is intended as a time saving device for projects, as they can\nfast approve requirements syncs and not have to manually worry about\nwhether or not they are up to date with the global definition.\n\nTools\n=====\n\nAll the tools require openstack_requirements to be installed (e.g. in a Python\nvirtualenv). They all have help, which is the authoritative documentation.\n\nupdate-requirements\n-------------------\n\nThis will update the requirements in a project from the global requirements\nfile found in ``.``. Alternatively, pass ``--source`` to use a different\nglobal requirements file::\n\n update-requirements --source /opt/stack/requirements /opt/stack/nova\n\nEntries in all requirements files will have their versions updated to match\nthe entries listed in the global requirements. Excess entries will cause\nerrors in hard mode (the default) or be ignored in soft mode.\n\ngenerate-constraints\n--------------------\n\nCompile a constraints file showing the versions resulting from installing all\nof ``global-requirements.txt``::\n\n generate-constraints -p /usr/bin/python2.7 -p /usr/bin/python3 \\\n -b blacklist.txt -r global-requirements.txt > new-constraints.txt\n\nedit-constraints\n----------------\n\nReplace all references to a package in a constraints file with a new\nspecification. Used by DevStack to enable git installations of libraries that\nare normally constrained::\n\n edit-constraints oslo.db \"-e file://opt/stack/oslo.db#egg=oslo.db\"\n\nProposing changes\n=================\n\nLook at the `Review Guidelines` and make sure your change meets them.\n\nAll changes to ``global-requirements.txt`` may dramatically alter the contents\nof ``upper-constraints.txt`` due to adding or removing transitive\ndependencies. As such you should always generate a diff against the current\nmerged constraints, otherwise your change may fail if it is incompatible with\nthe current tested constraints.\n\nRegenerating involves five steps.\n\n1) Install the dependencies needed to compile various Python packages::\n\n sudo apt-get install $(bindep -b)\n\n2) Create a reference file (do this without your patch applied)::\n\n generate-constraints -p /usr/bin/python2.7 -p /usr/bin/python3 \\\n -b blacklist.txt -r global-requirements.txt > baseline\n\n3) Apply your patch and generate a new reference file::\n\n generate-constraints -p /usr/bin/python2.7 -p /usr/bin/python3 \\\n -b blacklist.txt -r global-requirements.txt > updated\n\n4) Diff them::\n\n diff -p baseline updated\n\n5) Apply the patch to ``upper-constraints.txt``. This may require some\n fiddling. ``edit-constraint`` can do this for you **when the change\n does not involve multiple lines for one package**.\n\nReview Guidelines\n=================\n\nThere are a set of questions that every reviewer should ask on any\nproposed requirements change. Proposers can make reviewing easier by\nincluding the answers to these questions in the commit message for\ntheir change.\n\nGeneral Review Criteria\n-----------------------\n\n- No specifications for library versions should contain version caps\n\n As a community we value early feedback of broken upstream\n requirements, so version caps should be avoided except when dealing\n with exceptionally unstable libraries.\n\n If a library is exceptionally unstable, we should also be\n considering whether we want to replace it over time with one that\n *is* stable, or to contribute to the upstream community to help\n stabilize it.\n\n- Libraries should contain a sensible known working minimum version\n\n Bare library names are bad. If it's unknown what a working minimum\n is, look at the output of pip freeze at the end of a successful\n DevStack/tempest run and use that version. At least that's known to\n be working now.\n\n- Commit message should refer to consuming projects(s)\n\n Preferably, the comments should also identify which feature or\n blueprint requires the new specification. Ideally, changes should\n already be proposed, so that its use can be seen.\n\n- The blacklist is for handling dependencies that cannot be constrained.\n For instance, linters which each project has at a different release level,\n and which make projects fail on every release (because they add rules) -\n those cannot be globally constrained unless we coordinate updating all of\n OpenStack to the new release at the same time - but given the volunteer\n and loosely coupled nature of the big tent that is infeasible. Dependencies\n that are only used in unconstrained places should not be blacklisted - they\n may be constrained in future, and there's no harm caused by constraining\n them today. Entries in the blacklist should have a comment explaining the\n reason for blacklisting.\n\n- Reviews that only update ``projects.txt`` should be workflow approved\n alongside or before other reviews in order to have the OpenStack Proposal Bot\n propagation be useful as soon as possible for the other projects. For project\n removal or addition, the +1 from the current PTL (or core if the PTL proposed\n the change) should be enough.\n\nFor new Requirements\n--------------------\n\n- Is the library actively maintained?\n\n We *really* want some indication that the library is something we\n can get support on if we or our users find a bug, and that we\n don't have to take over and fork the library.\n\n Pointers to recent activity upstream and a consistent release model\n are appreciated.\n\n- Is the library good code?\n\n It's expected, before just telling everyone to download arbitrary 3rd\n party code from the internet, that the submitter has taken a deep dive\n into the code to get a feel on whether this code seems solid enough\n to depend on. That includes ensuring the upstream code has some\n reasonable testing baked in.\n\n- Is the library python 3 compatible?\n\n OpenStack will eventually need to support python 3. At this point\n adding non python 3 compatible libraries should only be done under\n *extreme* need. It should be considered a very big exception.\n\n- Is the library license compatible?\n\n The library should be licensed as described in `Licensing requirements`_,\n and the license should be described in a comment on the same line as the\n added dependency. If you have doubts over licensing compatibility, like\n for example when adding a GPL test dependency, you can seek advice from\n Robert Collins (lifeless), Monty Taylor (mordred) or Jim Blair (jeblair).\n\n- Is the library already packaged in the distros we target (Ubuntu\n latest / Fedora latest)?\n\n By adding something to OpenStack ``global-requirements.txt`` we are\n basically demanding that Linux Distros package this for the next\n release of OpenStack. If they already have, great. If not, we should\n be cautious of adding it. :ref:`finding-distro-status`\n\n- Is the function of this library already covered by other libraries\n in ``global-requirements.txt``?\n\n Everyone has their own pet libraries that they like to use, but we\n do not need three different request mocking libraries in OpenStack.\n\n If this new requirement is about replacing an existing library with\n one that's better suited for our needs, then we also need the\n transition plan to drop the old library in a reasonable amount of\n time.\n\n- Is the library required for OpenStack project or related dev or\n infrastructure setup? (Answer to this should be Yes, of course)\n Which?\n\n Please provide details such as gerrit change request or launchpad\n bug/blueprint specifying the need for adding this library.\n\n- If the library release is managed by the Openstack release process does\n it use the `cycle-with-intermediary` release type?\n\n This is needed to ensure that updated releases that consume requirements\n updates are available for integration/coninstallability tests with other\n projects.\n\n- Do I need to update anything else?\n\n When new library is added, initial version of release needs to be added\n to ``upper-constraints.txt``. After that, OpenStack Proposal Bot will\n propose updates.\n\n.. _Licensing requirements: https://governance.openstack.org/tc/reference/licensing.html\n\nFor Upgrading Requirements Versions\n-----------------------------------\n\n- Why is it impossible to use the current version definition?\n\n Everyone likes everyone else to use the latest version of their\n code. However, deployers really don't like to be constantly updating\n things. Unless it's actually **impossible** to use the minimum\n version specified in ``global-requirements.txt``, it should not be\n changed.\n\n Leave that decision to deployers and distros.\n\n- Changes to update the minimum version of a library developed by the\n OpenStack community can be approved by one reviewer, as long as the\n constraints are correct and the tests pass.\n\n.. _finding-distro-status:\n\nFinding Distro Status\n---------------------\n\nFrom the OpenStack distro support policy:\n\nOpenStack will target its development efforts to latest Ubuntu/Fedora,\nbut will not introduce any changes that would make it impossible to\nrun on the latest Ubuntu LTS or latest RHEL.\n\nAs such we really need to know what the current state of packaging is\non these platforms (and ideally Debian, Gentoo, and SUSE as well).\n\nFor people unfamiliar with Linux Distro packaging you can use the\nfollowing tools to search for packages:\n\n- Ubuntu - http://packages.ubuntu.com/\n- Fedora - https://apps.fedoraproject.org/packages/\n- Gentoo - https://packages.gentoo.org/\n- SUSE - https://build.opensuse.org/project/show/devel:languages:python\n\nFor ``upper-constraints.txt`` changes\n-------------------------------------\n\nIf the change was proposed by the OpenStack CI bot, then if the change has\npassed CI, only one reviewer is needed and they should +2 +A without thinking\nabout things.\n\nIf the change was not proposed by the OpenStack CI bot, and only\nchanges the ``upper-constraints.txt`` entry for a new library release,\nthen the change should be approved if it passes the tests. See the\nREADME.rst in openstack/releases for more details of the release\nprocess.\n\nIf the change was not proposed by the OpenStack CI bot, and is not\nrelated to releasing one of our libraries, and does not include a\n``global-requirements.txt`` change, then it should be rejected: the CI\nbot will generate an appropriate change itself. Ask in\n#openstack-infra if the bot needs to be run more quickly.\n\nOtherwise the change may be the result of recalculating the constraints which\nchanged when a ``global-requirements.txt`` change is proposed. In this case, ignore\nthe changes to ``upper-constraints.txt`` and review the\n``global-requirements.txt`` component of the change.\n\nstable-branch maintenance\n-------------------------\n\nUpper-constraints\n+++++++++++++++++\n\nMost of the work is done by stable-maint in the releases project. The releases\nproject ensures valid stable releases (little to no API level changes, bugfix\nonly, etc). Once released, the new version is requested to be updated in\nrequirements. The following restrictions are in place to help ensure stable\nbranches do not break.\n\n- In stable branches, we usually only update constraints for projects managed\n within the OpenStack community. Exceptions are made for other projects when\n there are gate issues. Those updates must be proposed by hand.\n\n- The requirements team also verifies the new version's requirements changes\n line up with the requirements in the stable branch (GR and UC).\n\nGlobal-requirements\n+++++++++++++++++++\n\nThese should be few and far between on stable branches, mainly masking known\nbad versions or in extreme adding a maximum version allowable for a package.\nWe work to remove these caps as well. Raising effective minimums is only\nacceptable during `Phase I`, and only due to security issues.\n\n.. _Phase I: https://docs.openstack.org/project-team-guide/stable-branches.html#support-phases\n\nNew requirements\n++++++++++++++++\n\nIn nearly all cases this is not allowed. An example where this is allowed\nwould be: A dependency of a dependency has an issue that impacts OpenStack.\nIt wasn't listed in global-requirements.txt but it is required. In order to\nblock the affected releases and still be able to keep requirements in sync, we\nlist the library in global-requirements.txt and update all projects that\nrequire it.\n\nResources\n=========\n\n- Documentation: https://docs.openstack.org/requirements/latest/\n- Wiki: https://wiki.openstack.org/wiki/Requirements\n- Bugs: https://launchpad.net/openstack-requirements\n\n\n\n", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://docs.openstack.org/requirements/latest/", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "openstack-requirements", "package_url": "https://pypi.org/project/openstack-requirements/", "platform": "", "project_url": "https://pypi.org/project/openstack-requirements/", "project_urls": { "Homepage": "https://docs.openstack.org/requirements/latest/" }, "release_url": "https://pypi.org/project/openstack-requirements/1.2.0/", "requires_dist": [ "fixtures (>=3.0.0)", "Parsley (>=1.2)", "six (>=1.10.0)", "packaging (>=16.5)", "requests (>=2.14.2)", "PyYAML (>=3.10)" ], "requires_python": "", "summary": "OpenStack python dependency management tools", "version": "1.2.0" }, "last_serial": 3576455, "releases": { "0.0.1.dev4132": [], "1.0.0": [ { "comment_text": "", "digests": { "md5": "9c1b7d1b5de3aa2e998dcbeab1fe809d", "sha256": "fc3684aba8ba6cee90fe725cf8536b8c5410d742e925a6899736432e1fa513db" }, "downloads": -1, "filename": "openstack_requirements-1.0.0-py2-none-any.whl", "has_sig": false, "md5_digest": "9c1b7d1b5de3aa2e998dcbeab1fe809d", "packagetype": "bdist_wheel", "python_version": "py2", "requires_python": null, "size": 59894, "upload_time": "2016-11-15T19:52:12", "url": "https://files.pythonhosted.org/packages/75/67/d51304fbc6650ce025ce23e4f6ddbc2b0b81cb411509ced192f3524b4d27/openstack_requirements-1.0.0-py2-none-any.whl" }, { "comment_text": "", "digests": { "md5": "43de6f8d600dc7ba18a5a50208519b7c", "sha256": "c7555e393ed18361310c54fb3029bd706f82c8812710ddc623996c09d08a0a05" }, "downloads": -1, "filename": "openstack_requirements-1.0.0.tar.gz", "has_sig": false, "md5_digest": "43de6f8d600dc7ba18a5a50208519b7c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 95597, "upload_time": "2016-11-15T19:52:15", "url": "https://files.pythonhosted.org/packages/a2/da/335b20d9078cdfced459956795836df7d3b19186ef57f694d6b46698e07b/openstack_requirements-1.0.0.tar.gz" } ], "1.1.0": [ { "comment_text": "", "digests": { "md5": "ed64c4d3749ddf6ad729f9cad1ee1ce3", "sha256": "313a7be86744a97ba32bd0403dc2b5affb3d6d860136171b657c00181a6fc3ca" }, "downloads": -1, "filename": "openstack_requirements-1.1.0-py2-none-any.whl", "has_sig": false, "md5_digest": "ed64c4d3749ddf6ad729f9cad1ee1ce3", "packagetype": "bdist_wheel", "python_version": "py2", "requires_python": null, "size": 72042, "upload_time": "2017-07-17T12:06:50", "url": "https://files.pythonhosted.org/packages/af/21/36f5a3bf74e4e5c885e8f8adfed748f34173752de97766b02f379561e5fd/openstack_requirements-1.1.0-py2-none-any.whl" }, { "comment_text": "", "digests": { "md5": "e597ad053c64f164aaf359aa76ec0d37", "sha256": "eba19c9ff69a2d9ab36f59331f6c494e0deff277402f03da359192349cfec8b5" }, "downloads": -1, "filename": "openstack_requirements-1.1.0.tar.gz", "has_sig": false, "md5_digest": "e597ad053c64f164aaf359aa76ec0d37", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 122630, "upload_time": "2017-07-17T12:06:53", "url": "https://files.pythonhosted.org/packages/67/62/1c2fc073d57a06bc360f3b68462141f54dc79e98334e7177faa0f4cdb9ef/openstack_requirements-1.1.0.tar.gz" } ], "1.2.0": [ { "comment_text": "", "digests": { "md5": "e8cfc6f6a5cdb063c53746734c547ba8", "sha256": "59c60f89f5137ad06422d09e65b99a1410da2cdd45c3278e2bdf8c98c56ea8cb" }, "downloads": -1, "filename": "openstack_requirements-1.2.0-py2-none-any.whl", "has_sig": false, "md5_digest": "e8cfc6f6a5cdb063c53746734c547ba8", "packagetype": "bdist_wheel", "python_version": "py2", "requires_python": null, "size": 72167, "upload_time": "2018-02-12T22:02:14", "url": "https://files.pythonhosted.org/packages/5a/8a/51b9d30e07ddd5032634c5234801b39a27dd3d58444c80a9c6e0c4edae8a/openstack_requirements-1.2.0-py2-none-any.whl" }, { "comment_text": "", "digests": { "md5": "b66c897c43254600a254aae1d7a445b5", "sha256": "c7038cf946511a4ed21e75b4db2130af58aa5b3867a1d6cc24e989915ef1d6f4" }, "downloads": -1, "filename": "openstack_requirements-1.2.0.tar.gz", "has_sig": false, "md5_digest": "b66c897c43254600a254aae1d7a445b5", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 135776, "upload_time": "2018-02-12T22:02:17", "url": "https://files.pythonhosted.org/packages/6c/18/3175b52048fc7ac475a3f0b4f9176f3a1d3f03b1448aeb5479771e11e201/openstack_requirements-1.2.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "e8cfc6f6a5cdb063c53746734c547ba8", "sha256": "59c60f89f5137ad06422d09e65b99a1410da2cdd45c3278e2bdf8c98c56ea8cb" }, "downloads": -1, "filename": "openstack_requirements-1.2.0-py2-none-any.whl", "has_sig": false, "md5_digest": "e8cfc6f6a5cdb063c53746734c547ba8", "packagetype": "bdist_wheel", "python_version": "py2", "requires_python": null, "size": 72167, "upload_time": "2018-02-12T22:02:14", "url": "https://files.pythonhosted.org/packages/5a/8a/51b9d30e07ddd5032634c5234801b39a27dd3d58444c80a9c6e0c4edae8a/openstack_requirements-1.2.0-py2-none-any.whl" }, { "comment_text": "", "digests": { "md5": "b66c897c43254600a254aae1d7a445b5", "sha256": "c7038cf946511a4ed21e75b4db2130af58aa5b3867a1d6cc24e989915ef1d6f4" }, "downloads": -1, "filename": "openstack_requirements-1.2.0.tar.gz", "has_sig": false, "md5_digest": "b66c897c43254600a254aae1d7a445b5", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 135776, "upload_time": "2018-02-12T22:02:17", "url": "https://files.pythonhosted.org/packages/6c/18/3175b52048fc7ac475a3f0b4f9176f3a1d3f03b1448aeb5479771e11e201/openstack_requirements-1.2.0.tar.gz" } ] }