Create Phrozn Bundle


One of the main priorities when developing Phrozn's core was making contribution process as straight-forward as possible. In an effort to provide easier way to create add-on code, Phrozn supports bundles.

The idea is really simple. Phrozn already supports pluggable code, so that custom functionality can be injected without hacking the core. Still moving plugin code from project to project might be tedious. So, instead of manual file transfers from project to project, you create a releasable and easily deployable archive with all the plugin code required for particular functionality. The final result (typically a tgz archive) is to be pushed it into some place where others can access it (like official Phrozn Bundles Repository).

Bundle is nothing more but archived directory (in pre-defined format) containing your custom functionality.

If you want to know how to use bundles, visit documentation page for phr bundle command.

Time to create our first Phrozn bundle!

Step1. Fork the official bundles repository

Strictly speaking you are not required to fork the official bundles repository, and can proceed with your own distribution model. As long as resultant archive file can be read, Phrozn will be able to apply the bundle.

If you want to share your code with the rest of Phrozn community, best way to do so is to distribute your code using Phrozn Bundles Repository. Once your code hits the repository, others will be able to apply it without any additional legwork.

So, go and fork the repository right now, I will be here waiting..

It is preferred that you create a "topic/feature" branches and not committing directly into your fork's master branch. That way merging is a more straight-forward process.

If the only reaction to previous note is "what the heck does it mean??", I really suggest you to go through well-written and very useful A successful Git branching model article.

Step2. Create and package your plugin code

Once you clone forked repository locally, you can start putting your shiny plugin code together.

First, create uniquely named directory which will contain your bundle. Right now there's no restrictions on how you name your bundle, but in future, once plugin architecture is solidified, your bundle might be renamed (put into differently named directory).

Since contents of your bundle will be put into project's directory (that's .phrozn directory) anything you can put into .phrozn, you can put into bundle folder: entries, styles, scripts, plugins etc.

Let's consider you crafted some theme and want to be able to apply it to another Phrozn projects easily.

Let's say your theme is described by following files (WRT to .phrozn folder):

As you see, there are quite a few files (both static and dynamic plugin code).

One way to apply those files to another project is to copy all these files manually. Granted, it works. But it is not funny at all (and we are here for fun, right?). Plus, it doesn't sound like a suitable method if you want some basic style applied to every Phrozn project you create. Luckily, Phrozn supports bundles :)

So, all those files go into your bundle directory, and as such can be applied en masse.

Step3. Prepare bundle meta-data

Again, this step is not required if you do not plan to contribute your bundle into Phrozn Bundles Repository.

This step is simple, just create your-bundle-name.yml file with following contents (with place-holders filled):

name: YourBundleName
description: |
    Some description of your bundle.
version: 1.0
author: Your Name

Step4. Send pull request

Now, the only thing left to do is sending pull request via GitHub. As said before, once your bundle will be pulled and merged into master branch, everyone having phr running will be able to use it.

If you are working on private bundle (that's the one you do not plan to share via Bundles Repo), all you need to do is archiving the bundle folder.

Internally, Phrozn uses Phing project to automate any task worth automating (including bundle archiving), but you can archive manually of course:

$ cd my-bundle-folder
$ tar -czvf ../my-bundle-folder.tgz .

If you are interested in how Phing is used to create bundles check out build.xml on GitHub.


Generated on 14 Jan, 2014 using Phrozn 0.5.6.

Fork me on GitHub