Modules for the XP Framework, 6.0

module.md

Modules for the XP Framework, 6.0

The goal

We want to modularize our code in order to encourage people to work on small and manageable chunks of the framework, which we'll call modules. The workflow to start working on such a module should consist of the smalles possible amount of steps. Ideally, given PHP and the XP Framework have been installed before, a git clone would suffice to start working:

# Set up - this is all that's necessary
$ git clone $remote/$lib
$ cd $lib

# Start hacking, test, commit
$ $EDITOR src/...
$ git ci -a -m 'Initial implementation of $feature'
$ unittest src/test/php
$ git push 

While this works fine for modules with dependencies only on the framework itself, it gets tougher for modules depending on other modules, and even more of a hassle if these modules themselves have dependencies. Additionally, the library may require development time dependencies, such as profiling tools, or unittest extensions such as a mock library.

Strategies

In order to achieve the goal above, there seem to be the following general strategies:

1. Bundle all dependencies in release form
2. Only add references, add additional step to fetch and reference
3. Use "git:externals" solution
4. Create a wrapper around git to checkout code and dependencies

1 - Bundle releases

# Clone
$ git clone $remote/$lib
$ cd $lib

# Discover dependencies
$ cat dependencies | xargs $download-and-reference

# Start hacking
...

Current situation: A typical library project

Using PHP Sourcecode, to be included inside a project, e.g. "mustache".

Development                         Release included inside project
=================================== ===================================

$lib                                $project
|- src/main/php                     |- class.pth
|  `- com/example/**.php            |- lib/$lib-1.0.0.xar
|- src/test/php                     |  |- ChangeLog-1.0.0.md
|  `- com/example/unittest/**.php   |  |- VERSION
|- class.pth                        |  `- com/example/**.php
|- ChangeLog.md                     `- lib/$lib-tests-1.0.0.xar
`- README.md                           `- com/example/unittest/**.php

cl[]=src/main/php                   cl[]=lib/$lib-1.0.0.xar
cl[]=src/test/php                   cl[]=lib/$lib-tests-1.0.0.xar

Including the tests should be optional, that's why their distributed as a separate file.

Development                         Development as part of project
=================================== ===================================

$lib                                $project
|- src/main/php                     `- class.pth
|  `- com/example/**.php
|- src/test/php
|  `- com/example/unittest/**.php
|- class.pth
|- ChangeLog.md
`- README.md

cl[]=src/main/php                   cl[]=../lib/$lib/src/main/php
cl[]=src/test/php                   cl[]=../lib/$lib/src/test/php

Here, the user is forced to adhere to a given filesystem layout. An alternative would be check out the development directory structure into a subdirectory of the project, e.g. ./lib/$lib@dev/.

Idea

cl[][email protected]