Difference between revisions of "Oslo"
(Document backwards compatibility decision) |
(→cookiecutter) |
||
Line 89: | Line 89: | ||
'''Documentation''': http://docs.openstack.org/developer/cliff/ | '''Documentation''': http://docs.openstack.org/developer/cliff/ | ||
− | === cookiecutter === | + | === openstack-cookiecutter === |
'''Summary''': a project that creates a skeleton OpenStack project from a set of templates. | '''Summary''': a project that creates a skeleton OpenStack project from a set of templates. |
Revision as of 19:01, 24 May 2016
Revised on: 5/24/2016 by Harlowja
Official Title: OpenStack Common Libraries
PTL: Joshua Harlow <harlowja@gmail.com>
To produce a set of python libraries containing code shared by OpenStack projects. The APIs provided by these libraries should be high quality, stable, consistent, documented and generally applicable.
Contents
- 1 The Oslo Team
- 2 Backwards Compatibility
- 3 Jobs
- 4 Libraries
- 4.1 automaton
- 4.2 cliff
- 4.3 openstack-cookiecutter
- 4.4 debtcollector
- 4.5 futurist
- 4.6 osprofiler
- 4.7 oslo.cache
- 4.8 oslo.concurrency
- 4.9 oslo.context
- 4.10 oslo.config
- 4.11 oslo-cookiecutter
- 4.12 oslo.db
- 4.13 oslo.i18n
- 4.14 oslo.log
- 4.15 oslo.messaging
- 4.16 oslo.middleware
- 4.17 oslo.policy
- 4.18 oslo.privsep
- 4.19 oslo.reports
- 4.20 oslo.rootwrap
- 4.21 oslo.serialization
- 4.22 oslo.service
- 4.23 oslosphinx
- 4.24 oslotest
- 4.25 oslo.utils
- 4.26 oslo.versionedobjects
- 4.27 oslo.version
- 4.28 oslo.vmware
- 4.29 pylockfile
- 4.30 hacking
- 4.31 pbr
- 4.32 pyCADF
- 4.33 stevedore
- 4.34 taskflow
- 4.35 tooz
- 5 Principles
- 6 Incubation
- 7 FAQs
- 8 Resources
- 9 Summits
The Oslo Team
The Oslo program brings together generalist code reviewers and specialist API maintainers. They share a common interest in tackling copy-and-paste technical debt across the OpenStack project.
Generalist Code Reviewers
Oslo's core reviewers take on a generalist role on the project. They are folks with good taste in Python code, provide constructive input in their reviews and make time to review any patches submitted to the project, irrespective of the area which a given patch targets.
Specialist API Maintainers
Each API typically has one or more specialist maintainers who have responsibility for evolving the API in question. They work to ensure the API meets the needs of all OpenStack projects, and once the API is stable and useful. Each library has its own core team, which can include specialists in the area of the library who are not general Oslo cores. Because the scope of the Oslo project has grown so large, these library-specific cores are **critical** to the long-term health of the projects and anyone with an interest in a library is encouraged to get involved.
Project Meetings
See Meetings/Oslo.
Getting in Touch
We use the openstack-dev@lists.openstack.org mailing list for discussions and we all hang out in #openstack-oslo and #openstack-dev on freenode.
Each project also designates a liaison for handling integration issues. See Oslo/ProjectLiaisons.
Backwards Compatibility
As of the Newton summit, where a vote of 10 Oslo cores was 7 in favour, 0 against, 3 abstained, Oslo projects maintain backwards compatibility for one release cycle: a maximum period of 12 months (start of one release cycle to the end of the next). We do this so that important improvements in master that aren't suitable for backporting to a stable branch are still able to be used by deployers. For instance, we fixed heartbeat in oslo.messaging in this manner, and have an upcoming kafka support change that requires upgrading support libraries we use across incompatible versions: our users won't suffer, but folk using python-kafka directly would, making it unsuitable for stable backports.
To test this, we will be implementing both stable jobs on master oslo changes (run stable devstack on master oslo) and unstable jobs on stable server changes (run the server with latest-oslo-release).
We are not specifically aiming to support partial mixed upgrades (e.g. Nova Mitaka + Neutron Newton) in a single Python environment: there are no obvious hurdles to that from the Oslo side, but client library Python API compatibility is not governed by Oslo policies.
Jobs
History of (these) jobs: https://etherpad.openstack.org/p/dims-periodic-jobs
Periodic
Oslo (dvsm) latest against master
Oslo latest against (many projects) master
Other periodic jobs: http://logs.openstack.org/periodic/
Libraries
The following libraries are currently published by the Oslo program. Where we felt that a library had real potential for widespread use outside OpenStack, we chose not to include them in the oslo namespace (aka prefix them with oslo).
New libraries need to be careful to avoid introducing circular dependencies. See Oslo/Dependencies.
Specialized libraries have their own core-review team with members who may not be part of the main Oslo core team. Unless otherwise indicated below, an Oslo library is maintained by oslo-core.
automaton
Summary: a framework for building state machines.
Proposal: 141961
Source: http://git.openstack.org/cgit/openstack/automaton
Bugs: please file bugs in the automaton project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/automaton/
cliff
Summary: a framework for building command line programs.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/cliff
Bugs: please file bugs in the python-cliff project in launchpad.
Core review team: cliff-core
Documentation: http://docs.openstack.org/developer/cliff/
openstack-cookiecutter
Summary: a project that creates a skeleton OpenStack project from a set of templates.
Proposal: 42530
Source: http://git.openstack.org/cgit/openstack-dev/cookiecutter
Bugs: please file bugs in the oslo project in launchpad.
Core review team: oslo-core
Documentation: n/a
debtcollector
Summary: a collection of python patterns that help you collect your technical debt in a non-destructive manner (following deprecation patterns and strategies and so-on).
Proposal: 141220
Source: http://git.openstack.org/cgit/openstack/debtcollector
Bugs: please file bugs in the debtcollector project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/debtcollector/
futurist
Summary: a collection of async functionality and additions from the future.
Proposal: 179890
Source: http://git.openstack.org/cgit/openstack/futurist
Bugs: please file bugs in the futurist project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/futurist/
osprofiler
Summary: an OpenStack cross-project profiling library.
Proposal: 103825
Source: http://git.openstack.org/cgit/openstack/osprofiler
Bugs: please file bugs in the osprofiler project in launchpad.
Core review team: osprofiler-core
Documentation: http://docs.openstack.org/developer/osprofiler
oslo.cache
Summary: a library for caching based on dogpile.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.cache
Bugs: please file bugs in the oslo.cache project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.cache/
oslo.concurrency
Summary: a project with helpers managing external processes and task synchronization.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.concurrency
Bugs: please file bugs in the oslo.concurrency project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.concurrency/
oslo.context
Summary: a project with helpers to maintain useful information about a request context (aka associated information/data bound to a request).
Proposal: see this historical blueprint describing the initial requirements for the API.
Source: http://git.openstack.org/cgit/openstack/oslo.context
Bugs: please file bugs in the oslo.context project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.context/
oslo.config
Summary: a extensive library for parsing configuration files and command line arguments.
Proposal: see this historical blueprint describing the initial requirements for the API.
Source: http://git.openstack.org/cgit/openstack/oslo.config
Bugs: please file bugs in the oslo.config project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.config/
oslo-cookiecutter
Summary: is a project that creates a skeleton Oslo library from a set of templates.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack-dev/oslo-cookiecutter
Bugs: please file bugs in the oslo-cookiecutter project in launchpad.
Core review team: oslo-core
Documentation: ??
oslo.db
Summary: a extensive library to aid in database interactions and/or handling.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.db
Bugs: please file bugs in the oslo.db project in launchpad.
Core review team: oslo-db-core
Documentation: http://docs.openstack.org/developer/oslo.db/
oslo.i18n
Summary: a wrapper library around Python's gettext module for string translation and other internationalization features.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.i18n
Bugs: please file bugs in the oslo.i18n project in launchpad
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.i18n/
oslo.log
Summary: a logging configuration library.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.logging
Bugs: please file bugs in the oslo.log project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.log/
oslo.messaging
Summary: a library that provides a messaging API which supports RPC and notifications over a number of different messaging transports.
Proposal: this etherpad captures the latest status and background to this project.
Source: http://git.openstack.org/cgit/openstack/oslo.messaging
Bugs: please file bugs in the oslo.messaging project in launchpad.
Core review team: oslo-messaging-core
Documentation: http://docs.openstack.org/developer/oslo.messaging/
oslo.middleware
Summary: provides a collection of WSGI middleware for web service development.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.middleware
Bugs: please file bugs in the oslo.middleware project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.middleware/
oslo.policy
Summary: provides a rules engine for enforcing policy.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.policy
Bugs: please file bugs in the oslo.policy project in launchpad.
Core review team: oslo-policy-core
Documentation: http://docs.openstack.org/developer/oslo.policy/
oslo.privsep
Summary: provides a mechanism for running selected python code with elevated privileges
Proposal: 204073
Source: http://git.openstack.org/cgit/openstack/oslo.privsep
Bugs: please file bugs in the oslo.privsep project in launchpad
Core review team: oslo-privsep-core
Documentation: http://docs.openstack.org/developer/oslo.privsep/
oslo.reports
Summary: allows projects to generate Guru Meditation Reports for debugging the current state of OpenStack processes. It can also be used to generating general reports on the fly that are serializable as plain text, JSON, or XML.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.reports
Bugs: please file bugs in the oslo.reports project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.reports/
oslo.rootwrap
Deprecated (with preference to oslo.privsep)
Summary: rootwrap allows fine filtering of shell commands to run as root from OpenStack services.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.rootwrap
Bugs: please file bugs in the oslo.rootwrap project in launchpad
Core review team: oslo-rootwrap-core
Documentation: http://docs.openstack.org/developer/oslo.rootwrap/
oslo.serialization
Summary: is a library that provides serialization functionality with special handling for some common types used in OpenStack.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.serialization
Bugs: please file bugs in the oslo.serialization project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.serialization/
oslo.service
Summary: is a helper library that provides functionality for running OpenStack services.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.service
Bugs: please file bugs in the oslo.service project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.service/
oslosphinx
Summary: is a sphinx add-on library that provides theme and extension support for Sphinx documentation from the OpenStack project.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslosphinx
Bugs: please file bugs in the oslosphinx project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslosphinx/
oslotest
Summary: is a helper library that provides base classes and fixtures for creating unit and functional tests.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslotest
Bugs: please file bugs in the oslotest project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslotest/
oslo.utils
Summary: is a helper library that provides various low-level utility modules/code (that doesn't have a home anywhere else).
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.utils
Bugs: please file bugs in the oslo.utils project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.utils/
oslo.versionedobjects
Summary: is a library that helps deal with DB schema being at different versions than the code expects, allowing services to be operated safely during upgrades (among other things).
Proposal: 127532
Source: http://git.openstack.org/cgit/openstack/oslo.versionedobjects
Bugs: please file bugs in the oslo.versionedobjects project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/oslo.versionedobjects/
oslo.version
Summary: is a helper library that provides for getting the version for an installed piece of software from the python metadata that already exists.
Proposal: 40498
Source: http://git.openstack.org/cgit/openstack/oslo.version
Bugs: please file bugs in the oslo project in launchpad.
Core review team: oslo-core
Documentation: ??
oslo.vmware
Summary: provides for a shared location for code common to the VMware drivers in several projects.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/oslo.vmware
Bugs: please file bugs in the oslo.vmware project in launchpad.
Core review team: oslo-vmware-core
Documentation: http://docs.openstack.org/developer/oslo.vmware/
pylockfile
Deprecated
Summary: legacy (and adopted) inter-process lock management library.
Proposal:102202
Source: http://git.openstack.org/cgit/openstack/pylockfile
Bugs: please file bugs in the pylockfile project in launchpad.
Core review team: oslo-core
Documentation: http://docs.openstack.org/developer/pylockfile/
hacking
Summary: a library that provides a set of tools for enforcing coding style guidelines.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack-dev/hacking
Bugs: please file bugs in the hacking project in launchpad.
Core review team: hacking-core
Documentation: http://docs.openstack.org/developer/hacking/
pbr
Summary: pbr (or Python Build Reasonableness) is a add-on library that helps provide (and enforce) a set of sensible default setuptools behaviours.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack-dev/pbr
Bugs: please file bugs in the pbr project in launchpad.
Core review team: pbr-core
Documentation: http://docs.openstack.org/developer/pbr/
pyCADF
Summary: a python implementation of the DMTF Cloud Audit (CADF) data model.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/pycadf
Bugs: please file bugs in the pycadf project in launchpad.
Core review team: pycadf-core
Documentation: http://docs.openstack.org/developer/pycadf/
stevedore
Summary: a library for managing plugins for Python applications.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/stevedore
Bugs: please file bugs in the python-stevedore project in launchpad.
Core review team: stevedore-core
Documentation: http://docs.openstack.org/developer/stevedore/
taskflow
Summary: a library that helps create applications that handle state/failures... in a reasonable manner.
Proposal: n/a
Source: http://git.openstack.org/cgit/openstack/taskflow
Bugs: please file bugs in the taskflow project in launchpad.
Core review team: taskflow-core
Documentation: http://docs.openstack.org/developer/taskflow/
tooz
Summary: a library that aims at centralizing the most common distributed primitives like group membership protocol, lock service and leader election by providing a coordination API helping developers to build distributed applications.
Proposal: 122439
Source: http://git.openstack.org/cgit/openstack/tooz
Bugs: please file bugs in the python-tooz project in launchpad.
Core review team: tooz-core
Documentation: http://docs.openstack.org/developer/tooz/
Principles
APIs included in Oslo should reflect a rough consensus across the project on the requirements and design for that use case. New OpenStack projects should be able to use an Oslo API safe in the knowledge that, by doing so, the project is being a good OpenStack citizen and building upon established best practice.
To that end, we keep a number of principles in mind when designing and evolving Oslo APIs:
- The API should be generally useful and a "good fit" - e.g. it shouldn't encode any assumptions specific to the project it originated from, it should follow a style consistent with other Oslo APIs and should fit generally in a theme like error handling, configuration options, time and date, notifications, WSGI, etc.
- The API should already be in use by a number of OpenStack projects
- There should be a commitment to adopt the API in all other OpenStack projects (where appropriate) and there should be no known major blockers to that adoption
- The API should represents the "rough consensus" across OpenStack projects
- There should be no other API in OpenStack competing for this "rough consensus"
- It should be possible for the API to evolve while continuing to maintain backwards compatibility with older versions for a reasonable period - e.g. compatibility with an API deprecated in release N may only be removed in release N+2
Incubation
The Oslo Incubator is now dead. Refer to the announcement and the change clearing out the repository.
FAQs
Why aren't alpha releases of oslo.config published to PyPI?
See Choosing Version Numbers for the current policies related to versioning and releases.
Why does oslo.config have a CONF object? Global object SUCK!
Indeed. Well, it's a long story and well documented in mailing list archives if anyone cares to dig up some links.
Around the time of the Folsom Design Summit, an attempt was made to remove our dependence on a global object like this. There was massive debate and, in the end, the rough consensus was to stick with using this approach.
Nova, through its use of the gflags library, used this approach from commit zero. Some OpenStack projects didn't initially use this approach, but most now do. The idea is that having all projects use the same approach is more important than the objections to the approach. Sharing code between projects is great, but by also having projects use the same idioms for stuff like this it makes it much easier for people to work on multiple projects.
This debate will probably never completely go away, though. See this latest discussion in August, 2014.
Why does Oslo observe feature freeze
Feature freeze is a time to stabilize all of the new features that were added during a development cycle, but since Oslo projects don't necessarily release on the same six month schedule as the other OpenStack projects (or at all in the case of oslo-incubator) it might seem odd that Oslo observes feature freeze.
For the graduated libraries this serves the same purpose as for any of the other projects - it's a time for focusing on bug fixes and stability.
For oslo-incubator, the primary motivation is making last-minute fixes needed by other projects easier to sync. If a new feature lands in oslo-incubator and an unrelated bug is discovered by one of the consuming projects, it becomes a problem to sync just the bug fix to the project. When 11th hour bug fixes are needed it's best if the sync is as simple and small as possible. To avoid problems, oslo-incubator respects the feature freeze period just like any other project.
How does Oslo manage versions?
Resources
Review policies
These overlay the regular review rules for OpenStack as a whole.
- Automated changes - patches from 'openstack proposal bot' and 'transifex' which have passed CI checks can be +2+A by a single core reviewer
Review Links
(See http://git.openstack.org/cgit/openstack/oslo-incubator/tree/dashboards for the source files to create these links)
Security Team
In addition to OpenStack's Vulnerability Management team, some members of the Oslo team have indicated their willingness to help with security related issues in Oslo code. See Oslo/Security for the current list.
Design Proposals
We use the oslo-specs repo to track design proposals across all Oslo projects.
See the Spec Approval policy for details.
The blueprints on launchpad detail the changes currently underway to implement these specs.
Approved Specs are published separately.
Release Instructions
Summits
Newton
Mitaka
Liberty
Kilo
Juno
Juno Etherpads
Icehouse Etherpads
Etherpads from sessions at the Icehouse Design summit.
- Creating REST services with Pecan/WSME
- OpenStack Client Update
- Updates to hacking, our code style enforcement tool
- I18n policies of messages
- oslo.messaging - API design, plans for Icehouse
- oslo.config enhancements, including removing import side-effects from consumers
- Rootwrap: Icehouse plans
- State of affairs in DB schema migrations
- Towards more structured & qualified notifications
- Merge logging and notifications
- Writing a service synchronisation library
- Oslo incubated libraries status
- Aggressively split oslo-incubator
Messaging Related Work in Havana
During the Havana cycle, work is going on to re-design our messaging APIs and to add signatures and encryption to our messages.
See this etherpad for yet more details.
Havana Etherpads
Etherpads from sessions at the Havana Design summit.
- Oslo Status and Plans
- Pecan/WSME Status
- No-downtime DB migrations
- Rootwrap improvements for the Havana cycle
- Common packaging support and code analysis tools
- RPC API review
- ZeroMQ RPC for Ceilometer and Quantum
- Message queue access control
- RPC Message Signing and Encryption
- Zipkin tracing in OpenStack
- i18n strategy for OpenStack services
- Common XenAPI libary
Grizzly Etherpads
Etherpads from sessions at the Grizzly Design summit.
- Oslo status and plans
- Unified CLI, take 2
- Adding optional security to RPC
- Services framework for command and control
- Using the message bus for messaging
- Choosing a WSGI framework for API services
- XML request/response processing
- Entrypoints based plugins
- Unified rootwrap & password management
- A common database
- Instrumentation monitoring
Folsom Etherpads
Etherpads from sessions at the Folsom Design summit.