devot:eeDevoted to ExpressionEngine

Organizing an ExpressionEngine Add-On Collection

September 15, 2009
by Ryan Masuga

I have a very organized method of keeping EE add-ons catalogued on my machine, and it was this catalog that was the foundation of devot:ee’s add-on library. I always kept previous add-on versions, organized into folders with version numbers, as well as links to the homepage for an add-on and any other relevant pages, which usually included a link or two to the EE forums. On my local machine, the folder structure is basically Sites > EE > addons > addon type (extension, module, plugin) > Addon name (and developer) > Version Folder(s) and Links > Version Files.

For commercial add-ons, I would also include a .txt file in the main folder of the add-on that contained a list of licensed sites. For example, in my LG Better Meta [Leevi Graham] folder, I have a text file called “licensed_sites_better_meta.txt” that lists the sites on which I’m using a licensed copy of the extension. Sample contents:

Leevi Graham LG Better Meta Extension
List of sites licensed for use and purchase date.

2008-12-31 masugadesign.com
2008-12-31 monkeymania.com
2009-02-14 site2.com
2009-03-27 doiwantie6todie.com
2009-06-16 devot-ee.com

Organizing my collection in this way made it really easy to find add-ons and links and even to help out other EE developers who may not be so organized. Have you ever had anyone email you requests, or seen posts in the EE forums that resemble the following?

“Think you could post a copy of 1.0.2 for download? I accidentally borked the upgrade and it looks like I’ll need the old version to get back into my EE Control Panel.”

“I accidentally deleted the extension and it’s language file before disabling it from the control panel. Unfortunately I can’t re-upload the extension because it is an old version that is no longer available for download on your site. Do you have this older version so I can re-upload it to our site?”

Those are two messages I received regarding add-ons I put together for EE. It was easy for me to go back into a version folder and grab a zip file to attach to an email. I’ve even done this a few times in the EE forums for other developers. Someone needed an ancient copy of a particular extension and I was able to dig it up for them in a few seconds.

That was my method of organizing add-ons. Every add-on was pretty clear cut: a zip file attached to an EE forum post or found on a developer’s site. Nowadays a lot of add-ons are showing up on social coding sites like GitHub where all you have to do is clone the repository and update it with a git pull every now and then. This sounds easy enough, but does raise new questions.

Enter Social Coding

With the recent explosion of EE developers using GitHub, I started thinking about how different an organized library of add-ons might be. On one hand, it’s easy to see when a developer has made updates, but unless they’re using Git tags or thorough docs, you may not know which version you’re getting (or what build of the version), and with the ability for other developers to fork a project, things can begin to feel convoluted.

What the Fork?

Forking is when a developer makes a branch of your project. Let’s say you create an add-on called Freakotronic and you put version 1.0 on GitHub. People start clamoring for more parameters but you simply don’t have time. Developer 2 has some time to kill and needs a new parameter, so they fork your Freakotronic add-on and add the parameter, and don’t bother updating the version number. Now there are two 1.0 versions in existence: your basic offering, and Dev 2’s version with the extra parameter. Which would you download?

This, to me, is the slippery slope of trying to keep EE add-ons straight in the face of social coding. Here’s another scenario. You discover Awesome Addon X, version 1.2 that you download from an ExpressionEngine forum thread, and it does exactly what you need. Later you realize the developer has added the addon to GitHub, with a version 1.3. Then you discover that Joe Schmo has forked the original Awesome Addon X and added a few new parameters, but those haven’t been rolled back into the “main” add-on. You think the new parameters are awesome, so you download Joe Schmo’s version. Is this still considered a 1.3? Joe’s code indicates yes, so we’ll go with it. Then, a couple weeks later you realize that Larry Jones forked Joe’s fork to add one other absolutely necessary thing. You end up upgrading to that version instead. Everything is great. You are now using a fork of a fork that has more features than the original.

Two weeks later you install another extension and realize that, going all the way back to the original, Awesome Addon X was missing something essential (such as a Last Call [$EXT->last_call]) that allows it to play nice with other extensions. Who do you go to for support? You post in the EE forums “I’m using Larry’s fork from GitHub, which is a fork of Joe’s version which was a fork of the original. Larry doesn’t seem to care – he won’t answer my emails. Joe, could you update this extension for me, I have no idea how.”

You get the idea.

Who will maintain a particular fork if you decide to use it? Just because someone forks an add-on to add functionality doesn’t necessarily mean they’ll support it. What version is the “real” version? Who’s on first?

Not that this scenario wouldn’t have happened before, but GitHub makes it that much easier for it to come about.

Pros

New features get added faster
I had an issue with an extension. I notified the developer via his Get Satisfaction account, and within minutes the fix was posted to GitHub. All I had to do was perform a git pull to my local repository to get the latest changes.

You know you’re using the latest version (for better or for worse)
Changes taking place so fast may not have time to be properly or thoroughly tested, so in some instances, the latest may not be the greatest.

Cons

Support for forked versions may be non-existent
That fork of a fork you’ve been using for a few weeks may have no support at all – it could die on the vine.

There is no guarantee that 3rd-party updates will ever be made to the “official” version
Your best hope is that the original developer likes the changes and rolls them in to the main supported branch.

Cloning vs. Downloading

There’s no real need to keep numerous version folders when cloning a Git repository. If the developer is diligent enough to push Git tags, then it would be very simple to go back and grab a previous add-on version at any time, and to know exactly what version you currently have. I think cloning is superior to downloading versions because your local directories are far less cluttered, and the latest version of an add-on is always a simple git pull away.

To use an example, I want to make sure I’m using the latest version of FieldFrame before I install it on a new project. I’ve already cloned the repository from GitHub
, so now I just change directory (cd) to that folder. Typing git tag will show me all the tags for the repo. I see I’m at 1.3.3, so I type git pull to see if there is anything newer, but I’m assured that I’m already up to date with what I have.

~ : cd Sites/addons/fieldframe
~/Sites/addons/fieldframe (master): git tag
1.0.3
1.0.5
1.0.6
1.0.7
1.0.8
1.1.0
1.1.1
1.1.2
1.2.0
1.2.1
1.3.0
1.3.1
1.3.2
1.3.3
~/Sites/addons/fieldframe (master): git pull
Already up-to-date.

What are (Git) Tags?

Developers aren’t always pushing their tags to GitHub, so it’s sometimes hard to know exactly what version you’re getting. Developers may make small updates to their add-on at GitHub
, but not increment the version number – if they have version numbers at all.

Git tags are like snapshots, and they can be used for different things, but for the purposes of an EE developers, they could be used to store a version number. If the main distribution method for your EE add-on is GitHub, it’s probably a good idea to push a tag when you push your latest changes.

How to Push Git Tags

It takes just seconds to push tags to your GitHub repository so that users know what version they’re downloading. Alternately, they will be able to go back and download an older version if they choose.

There is a guide on pushing tags to GitHub.

In Conclusion

I don’t want to make it seem as if I’m harping on Git and GitHub as the be-all end-all way to distribute EE add-ons, but it’s what I’m familiar with, and many EE developers are using this as a way to distribute their work.

Overall, and in spite of possible issues with supporting the fork of a fork of a fork, I do think it’s easiest to keep track of add-ons when they’re stored in a public repository such as GitHub and I can easily clone even the smallest updates to the latest version or build to my local machine. I don’t have to go out to any website or buried forum post to look for a download link – just change to the directory and do a git pull and I’m done.

I didn’t even touch on the more advanced methods of utilizing these cloned repositories as submodules in all your local EE installs.

This article was intended more as a thought on how the face of EE add-on development is changing. As someone who has used EE for over three years now, I can see it changing before my eyes. New people, new techniques, new add-ons, and a growing sense of collaboration are making ExpressionEngine ever more versatile and enjoyable to work with.