OpenStack-SDK-PHP/TechnicalRequirements

Ease of installation

 * Composer/Packagist package (Priority 1)
 * PHAR file (Priority 2)

PEAR and Linux packages are not currently part of the requirements. If someone believes one of them should be handled please file a blueprint and make a case.

Ease of use

 * Human-readable service names: minimize usage of OpenStack codenames
 * Well-written and highly accessible end-user documentation that strives to be as comprehensive and helpful as possible
 * Assumption-free documention, capable of expressing a concept soundly to both novices and experts
 * Quick start guides for every service, starting with most popular ones
 * Consistent use of code samples [Discussion point: could we store these as sample files in GitHub or as gists and then include them from within the documentation?]
 * API documentation
 * PHP docblock annotations
 * A simple API that minimizes complexity and vendor differences
 * Multiple forums to make announcements and answer queries:
 * GitHub issues
 * IRC
 * -users@ mailing list [Discussion point: should this be different from the contributors mailing list (see section on contributing below)?]
 * Twitter account (similar to https://twitter.com/awsforphp)

Ease of contributing

 * Community-driven decisions with full feedback and transparency
 * A CONTRIBUTING guide, encouraging all forms of engagement
 * Active on irc channels
 * A mailing list
 * Google Hangout meetings

HTTP transport layer

 * Support for all HTTP request methods, including custom ones
 * Requests, responses, headers and URLs can be easily accessed and editable (i.e. they serve as objects)
 * Persistent connections
 * Connection pooling
 * Parallelization with multi-cURL
 * Request bodies are handled as streams rather than strings - to avoid in-memory storage
 * Ability to register a Swift stream wrapper, so that native filesystem functions can be utilized
 * Perhaps the ability to use `swift://` protocol
 * Flexible authentication
 * Auth caching
 * Multiple connection types offered through adapters: cURL, sockets, test/mock
 * Redirect handling
 * SSL support
 * Retry strategies (in response to cURL/HTTP errors, throttling, etc.)

General

 * Support for multiple service versions, easily selected by an end-user


 * The core library will contain common functionality essential to the running of a pure OpenStack installation

Extensions

 * Extensions, whether vendor-specific or not, need to be handled appropriately. There is a strong argument for extracting this supplementary functionality from the core library and placing it in other namespaces (or repositories)


 * Discussion point: Need to agree where to place / how to structure vendor extensions

Service clients

 * Discussion point: Need to agree whether each service will act as its own client, or whether a more global context will be used.


 * Discussion point: Need to agree the best way to define API services (json-schema, Guzzle DSL, userland code)


 * Discussion point: Need to agree the best way to create or marshall service objects from their descriptions - i.e. some form of service container

API concepts

 * We should objectify and properly abstract the basic concepts of a ReSTful API. For example: a service is composed of Resources
 * Each resource has state and is expressed through properties.
 * Discussion point: How strict should we be with API resource properties?
 * Each resource can be modified with ReSTful operations. Each operation is composed of the following:
 * A HTTP method
 * A URL (absolute or relative)
 * Parameters (key/val array)
 * A description
 * A definition of how its response will be parsed

Events

 * We should use Event dispatching to expose all moments of a request's lifecycle to the end-user. This allows them to add in or modify functionality as it suits them, rather than them having to extend and override main classes.
 * We should think about what "events" are most important for an end-user: request.before_send, request.sent, request.error, curl.progress, etc.

Iterators

 * We should support iterators and request-based append functionality.
 * We should make this as consistent as possible and hide any underlying inconsistencies.
 * We should also utilize native SPL iterators where possible.

Waiters

 * Ability for users to "wait for" an operation to achieve some state. For example, a user may want to wait until a Nova instance has finished building before continuing with their script.
 * This should be easy for an end-user to work with

Error handling

 * Error messages need to be as descriptive and helpful as possible. We should not expose them to an API message or HTTP status code.


 * Discussion point: Need to agree about how to use exception classes

Standardisation

 * PSR-2 coding style
 * PSR-3 logging interface
 * PSR-4 autoloading

Documentation
Discussion point: Need to discuss what technology or tooling we will use to write our end-user documentation - i.e. Sphinx, markup Discussion point: Need to decide how to host our documentation - i.e. Read the Docs or OpenStack domain

Methodology
Discussion point: Need to decide our testing methodology.

Tooling
Discussion point: Need to decide our testing tool.

Continuous integration
OpenStack has its own continuous integration framework, but we can probably use Travis in addition to that.
 * Travis?

Releases
* OpenStack already has a defined release schedule. IMHO we should assume we'll follow that unless there's a good reason to differ. That would be major releases twice per year and minor monthly releases in between.
 * Discussion point: When should we cut new releases? Should these be time-based or milestone-based?