[openstack-dev] [openstack-sdk-php] Review of face to face meeting on direction for SDK.

Shaunak Kashyap shaunak.kashyap at RACKSPACE.COM
Fri Aug 1 02:01:38 UTC 2014


Thanks for compiling this, Matt. I think you captured all the major points here; I just have three additions/changes:

    class RackspaceObject extends Object {}

I know this is the exact sample code we put up on the whiteboard and I know we totally didn’t discuss namespaces at all at the time.

Looking at this snippet now, though, I’m wondering if using namespaces here would be better so instead of RackspaceObject, the class name would be just Object but in the Rackspace namespace. Presumably the name of the class being extended would also be Object (as is the case in the sample code) but that class would be part of the OpenStack (or Core or something) namespace. Thoughts?

The idea is to use inheritance where needed. This style is quite common in PHP.

I’ll add here something I mentioned during our meeting: We would favor inheritance for scenarios such as extending an OpenStack-oriented class to a Rackspace-oriented class. We would favor composition and dependency injection for cross-cutting concerns such as logging.

Common properties could be protected while uncommon ones, or those we aren't sure of would be private.

Based on the example we tried out in http://3v4l.org/ (thanks for pointing us to this site, btw), I thought we were tending towards this convention: all properties would be private, their accessors (getters/setters) would either be public or protected; derived classes would access these properties via these accessor methods, using “parent::somePropertyAccessorMethod()” if necessary.

Thanks,

Shaunak

On Jul 31, 2014, at 6:40 PM, Matthew Farina <matt at mattfarina.com<mailto:matt at mattfarina.com>> wrote:

We just completed a meeting on the OpenStack SDK for PHP and this email attempts to sum up the discussion and action items to come from the meeting. This was a face to face meeting that included discussions of processes and architecture.

In attendance were,
- Glen Campbell, Rackspace
- Shaunak Kashyap, Rackspace
- Sam Choi, HP
- Matt Farina, HP

I want to thank everyone who came. This was a productive and good meeting.

The conversation opened with a discussion of process. We discussed the Gerrit and review process used by the OpenStack community and how Gerrit was configured for the PHP SDK codebase. Matt took an action item to document the process.

In addition to the process we discussed reasons a patchset in review would receive a -1 right away. These include:
- Duplicate effort
- Doesn't meet the coding standard
- The tests fail
- Counter to previously documented decision
- A work in progress (until we come up with a better way to handle that)
- Big feature not tied to a blueprint

We discussed the target audiences for PHP SDK work. The customers are, in priority order:
1. SDK Consumer
2. Builders of the SDK
3. Extenders of the SDK

Note, #2 and #3 are very close to each other and a distance behind #1.

When we looked at the SDK Consumer we documented we noted a number of projects that should be able to use the SDK easily. These include:
- Symfony
- Laravel
- Zend Framework
- Wordpress
- Drupal
- Joomla
- Spagetti Code

We also noted the difference between Products (that will be shipped) and services that use the code.

As part of the process we looked at breaking ties. Since the project is being entirely worked on by two companies it would be nice to have 3rd parties as a tie breaker. We discussed using the community. We decided to use a 3rd party agreed to arbitrator who is willing and we agree to. For example, someone like Larry Garfield (who we have not contacted yet but is an example of this type of person).

There were several topics where we came to technical direction.

The directory structure will be the following style...

    identity/v2/
    identity/v3/
    objectStore/v1/
    compute/v2/
    compute/v3/

A service for a version will be the point of reference. In an attempt to make extending or replacing the code for a service a viable option we're looking into interfaces at the level of a service with additional interface definition at the level of a service version. For example, compute could have an interface with a reboot method. Then compute v3 could have an interface that extends the compute interface and adds a compute v3 method/feature. Code consuming the these can check against the interfaces. Glen took an action item to arrange feedback on the interface style from some who have worked with this in the past for other SDKs.

When it comes to extending classes for functionality we came to a conclusion to use the style...

    class RackspaceObject extends Object {}

The idea is to use inheritance where needed. This style is quite common in PHP. Scoping (public/protected/private) for methods and properties was discussed. Common properties could be protected while uncommon ones, or those we aren't sure of would be private. The only public methods would be those defined by the interface.

An example of the scoping and using it in the inheritance model can be seen at http://3v4l.org/peMiO.

At the top an OpenStack general object could be used to make the experience easier. For example...

  $service = $openstack->service(...);

The ... here is an array with a well documented structure for service discovery from the service catalog. A session should be used to handle the identity and make it easy for users.

The end user style discussed was based on 3 differing options. The options discussed were..

1. An ORM style. For example,

    $object = $objectStore->getContainer('foo')->getObject('bar');

2. Working with objects directly. For example,

    $object = new Obejct();
    $object->setRegion('region');
    $object->setContainer('foo');
    ... (more sets)
    $object->load();

3. A DSL Style. For example,

    $object = $objectStorage->get(...)

Here ... is an array defining what to get.

The direction that clearly came forward was the #1 option. It was the one everyone tended towards.

We noted that we might want to add ->execute() to the end but that's an optimization we can look at in the future. It could optimize to minimize http requests.

To make it easier to understand end users, we want to have examples/tests of real world code developers consuming the code could use. This will help define APIs and real world needs. This should come before the implementing code or along with it.

Action Items
------------
- (Matt) Document the OpenStack/Gerrit workflow.
- Find 3rd party arbitrators.
- BDD or not to BDD decision.
- (Glen) Discussion into successes and failures of using interfaces.
- Document common properties to consider for protected scoping rather than private scoping.

Decisions
---------
- For disagreements we agree to use an agreed to arbitrator.
- Public scoping of methods is for those defined in interfaces.
- Example/test of how an end user should do something should come before functionality.
- Use a session to keep the identity around and useful. Re-authenticating from an expired token or something along those lines should be automatic.
- We need to document everything. This will be useful for later reference. There needs to be less tribal knowledge.


If I missed or was in error of something please let me know. I think I captured the big items here.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140801/b69bf730/attachment.html>


More information about the OpenStack-dev mailing list