Half-Elf on Tech

Thoughts From a Professional Lesbian

Tag: open source

You Can’t Be Everything

There’s no app out there that does everything.

A lot of you just said ‘I know.’ but did you ever stop to think about why that’s the case? After all, some applications do everything you need them to do, and some you don’t, so who gets to decide what is and isn’t needed? When I talked about how WordPress was just fine on it’s own, without any plugins, people stepped up and said “But Ipstenu, I really need XYZ.” Heck, Lorelle said she needed Akismet.

Learning how to separate your personal needs from the needs of the masses, when writing software, is a full-time job, and many of us come at it from a slant-wise point of view. In fact, writing core code for WordPress is in diametric opposition to why we write plugins! While I’m going to talk about it from a WordPress point of view, the concept holds true to any application that has ‘add ons.’

Plugins are written, by in large, to solve a specific problem. They’re not ‘fixing’ WordPress, they’re expanding. Remember, your iPhone wasn’t broken until it had Angry Birds, nor was your iPad incomplete without Twitter. Those are things you wanted, and solved a problem for you. The base tools, in and of themselves, address a broader group of people, with a diverse set of needs, and have the option of being everything or nothing.

The best tool, WordPress, your computer, etc, are built to be extendable. They’re built with the innate knowledge that the users may want things they can’t forsee. Five years ago, how many of you thought Google+ or Twitter would be a ‘thing’? Let’s take that further. You know how when a new video game comes out, sometimes you can’t play it on your older computer? That’s because it wasn’t built with the new game in mind, so it’s just not capable. And that’s why computers generally let you upgrade memory, CPU, and hard drives. They are built to be extendable becuase they know they can’t know the future.

Bringing it back to WordPress, it was built to meet a need. People wanted to blog, they wanted it to be easy and they wanted it to just bloody work! So the Matts said ‘This is what we want’ and built it. Thankfully, they understood that people wanted to extend WordPress. But not at first. Oh you didn’t know? Back in December 2003, a ‘new feature’ was introduced called my-hacks.php, which let you put a file by that name in the root of WP, and it would treat it like a functions file. In fact, that’s why I call my non-plugin code ‘hacks.’ Heck, we didn’t get pretty permalinks until January 2004 (then called ‘cruft free’ URLs).

The point of this is not to expose the funny looking beginnings, but to demonstrate the nature of the software. As it grew, people had needs, and instead of writing everything into core, they cleverly changed WordPress so it was extendable and let people grow as they needed. So when we talk about things like needs and wants, we do it in the understanding that we write our software to fill a need, and we make add-ons to fill wants. Sounds like double speak, I know, but that’s why I said plugins and core development are in direct opposition.

When I want to add things to core, I want them to be useful to everyone, so I’m forced to remove my ego from the equation. Looking at the (few) core submissions I’ve made, I carefully thought them out beforehand. I looked at places were the user experience was inconsistent or diminished. When I make suggestions or offer commentary to what I think could be better, I try to show my passion without acting like a teenager’s first big crush, or a screaming fangirl meeting her heroes.

This isn’t to say I don’t think passion is a part of the driving force of any product, but that it must be tempered and controlled in things like WordPress core. We know that we can’t make WordPress core do everything, and we know we shouldn’t. When things are extendable, we utilize that and demonstrate our fire. When they’re difficult to extend, or kludgy to implement, we come back and say ‘You know, it would be nice if we could…’ But at the end of the day, when WordPress tags your trac ticket ‘wontfix,’ it’s because they know, being unable to be all things, that they must limit the things they are.

If you haven’t yet, take the time to read WordPress’s Philosophy.

When I usually talk about divorcing my ego from a project, what I mean is that I don’t let my passion cloud my better judgement. One of the lessons I’ve learned in nearly 20 years of active fandom is that when you love something, you get fired up about it, and you tend to view peoples opinions and actions as a personal attack when, in fact, they often aren’t. Yes, there are idiots and trolls and people who hate-monger, but in general, people actually aren’t dicks. They’re selfish and self-centered, but that’s just human nature. Part of designing a project means you have to let go of your personal attachment to your baby, and understand that haters are just gonna hate, and there’s nothing you can do about it.

This also applies to using a tool, though. People mock the evangelists, and we all hate the extremists, and certainly no one actually supports those who are outright malicious. But all those archtypes come part and parcel with a system, and are all aspects of the simple problem that no one product can do all the things. We want things to be a silver bullet, to fix everything we, personally, have a problem with, and we’re totally unrealistic in wanting that.

Mark and I were talking recently, and he pointed out that WordPress was once 230kb. It’s now 3.8megs, even zipped up. Part of this is because it all grew and became more, but if you ask the old-timers, some will complain that around the 1.5 days, WordPress just became too big. It does too much! And those people say we should pull things like the importer out of WordPress. After all, you’re going to use it once, if at all. Core plugins would get pretty big too. Jetpack is 2.4megs on its own, zipped up. By trying to be everything, maybe we’re making things a little worse.

So the next time someone gets their panties in a bunch at you for not doing everything, tell that it’s by design. Do what you want with your code, make it easily extendable for the next guy (or forkable), and carry on. They’re not getting that unicorn.

30 May, 2012
How To Submit a WordPress Plugin
I’m not a super-psycho coder. But between being a busybody and being a volunteer plugin referee, I do spend a disproportionate amount of time looking at the code people put in for plugins, which means I actually see a lot more code, and a lot more submissions, than you might expect. This puts me in a place where I actually can offer some of the world’s most basic advice ever, that a surprising number of people seem to miss, about how to submit your plugins, what will get them downcheked, and what you really just shouldn’t do.

This list is not all encompassing, but touches on the issues I see the most often.

What You Must Do

Failing to do the following will likely end up in your plugin being yanked (or not approved at all).

Read The Guidelines

We are not pirates. These are not wishy-washy rules, though they are intentionally kept as light as possible. You see, the more you make a rule “You can’t do this!” then the more you get “Well, you said I couldn’t dig to China, not Australia!”(That’s a true story on my part. I once got my kindergarten school class to dig to China. After being told not to, I got them to dig to Australia. At this point, they said ‘No digging tunnels at school.’ My parents explained in more detail why this was dangerous, and we watched The Great Escape to understand tunnel collapse. I forget how Dad explained the distance, but I remember a long explanation about the earth’s core being molten, and no, you can’t dig under the ocean. I was bummed. I was also 4.) The basic guidelines are on the front page of the Developer Center, but it’s the expanded guidelines you really need to read. I helped write those guidelines (over beery emails with Otto) and he and I both hate that we have to spell certain things out, but apparently they’re unclear. Just read them. If you think you’re doing something that might be on the far side of okay, ask around. Tweet, post in the forums, or find a plugin dev you respect and ask them directly.

Check Licences

All plugins must be GPL2 (or later) compatible. This is pretty basic, but a lot of people don’t realize what that means. First, there’s the issue of GPL2 versus GPL3. While the WordPress repository accepts GPL3 plugins, it’s still not compatible with everything, so make sure the code you fold into the plugin will work with which ever license you chose. If you don’t want to use GPL, you don’t have to! Remember, there are a lot of GPL Compatible Licences. At the same time, there are a lot of incompatible licences as well. And there are the Non-free Software licenses. When you’re only releasing your own code, this is pretty easy. You pick a compatible license and move on. When you’re incorporating other people’s code, however you have to study their license carefully.

Generally I’ve seen people get dinged for using the Creative Commons license, and in most cases this is because they’re not using the CC0 license. That is the only CC license that really works with GPL (except for CC BY ND). Your code really shouldn’t be CC licensed, anyway, though. Just don’t use it.

Provide the code

When you submit your plugin, put in a link to the code so it can be downloaded and checked. (See Expanded Guidelines, Rule #16) If, for some reason, you can’t because the code is behind a paywall, or you don’t want it in the wild, don’t worry! The only people who see that link are the plugin review team, and they’re trustworthy. They don’t need an API key, either, they just want to make sure you’re not breaking the repo guidelines. If you don’t provide a link to the code, you don’t get in. It’s really that simple.

Don’t break the other WP rules

Did you know you can’t use ‘wordpress’ in your domain name without permission? If your author or plugin URL is http://mycoolwordpressplugins.com then your plugin will be rejected. (See Expanded Guidelines, Rule #17) In addition, you’re still going to be held subject to the forum rules with your account. I mention this because if you get blocked on the forums for rampant asshattery, you won’t be able to check new code in. Basically remember that it’s the internet, and we can see your behavior on Twitter, Forums, Faceybooky, etc. Don’t be an idiot.

What You Should Do

Not doing the following won’t get you punted from the repo, but they’re still good to do, in order to provide the best support possible.

Write a good readme

A good readme file is going to tell the person everything they need to know before they download the plugin. This means:
1. Describe what the plugin does
2. Explicitly state any and all requirements
3. Be upfront about any external accounts required (for APIs or what have you)
4. Inform users if their information is being sent to another site, where, and why (not necessarily technical explanations, just ‘Your IP, browser specs, etc will be sent to Google for Analytics purposes. This is required if you want to use Google Analytics.’)
5. Include screenshots of the options
6. Include a screenshot of what the plugin looks like on the unmodified default theme
7. Document if no support is provided (or if support is handled somewhere other than the WordPress forums)
Credit Appropriately

A subset of that is that if your plugin is a fork of someone else’s, be the good person and credit them! It’s not required all the time, but take a look at the copyright information on a plugin. Sometimes they say they require credit in the code. If so, you’ve got to do it. Even just a line that says “Copyright 2009-2011 Some Other Dude” and then “Copyright 2011 Me” below it. That’s a nice CYA. If you want to be really nice, put their userID under ‘contributors’ in the readme file, and they’ll have their pretty face on your plugin.

Write Good Code

Using good code is complicated. I don’t pretend to be the best at it myself (seriously, the level of shenanigans I went through over nonces cannot be measured on a human scale). But I know that good code is secure code. I know I should use nonces in certain situations, I know to protect against SQL injections, and I know to not let total strangers upload executable files (so they can’t upload a PHP file that wipes my DB, for example). And I know when to go find Otto, WePay him a beer, and say “So what the hell did I do wrong, here?”

Writing good code is exceptionally complicated, which is why, if you’re going to write a large plugin, you need to know what you’re getting into. The problem a lot of people get into is the classic ‘Your eyes are bigger than your stomach.’ When you write a plugin, keep it simple. Start with the code you know, slowly fold in the new stuff. Try to test as many different ways as you can think of, but know that you’re going to miss something.

What To Do If Your Plugin Is Yanked?

Every plugin developer’s worst nightmare is waking up to find that their plugin was yanked from the WordPress repository.

Don’t panic!

This happens when your plugin has been reported as possibly being in conflict with the developer guidelines, or it has a security hole. Many times you will not be notified when this happens. Sometimes you’re not notified because the report is found to be incorrect, and sometimes it’s because you’ve been warned before. And, once in a while, it’s because the person who closed your plugin doesn’t have the ability to email you. Surprise! There are some people on the plugin repository team who don’t have the access to the plugins email system, so when they close your plugin, they’ll ask someone else to email you. If that person is busy, it might take a while.

When a plugin is closed, the rest of your plugins are usually checked over to make sure they’re not also having an issue. For example, if you have one plugin with a front facing link that’s turned on by default, all your plugins will be checked for that and, if they all have the same problem, they will all be yanked. This is why you need to keep up to date on the plugin guidelines, and follow the WordPress Development Blog.

As soon as you find out your plugin is closed, email plugins@wordpress.org and ask what you can do to restore it. Posting in the forums won’t help much.
7 May, 2012
Fork With Restraint

I love that the GPL lets you fork. In fact, two of my plugins are forks and one’s an adoption. I think that’s one of the best things about GPL, the freedom to adapt and move on. But every single time you fork a plugin, you cause a couple problems that many people are either ignorant of or just don’t care about.

Confusion

If you look up ‘WP Grins’ there are three plugins. ‘WP Grins’ is the original, ‘WP Grins Lite’ is the first fork, and ‘WP Grins SSL’ is the third. Each one is pretty explanatory. The plugins are similar, but you get the idea from the title what’s different. And in each case, each forker took the time to say ‘this is what’s different’ in obvious ways, and to credit those who came before. This is important because, based on name alone, there’s not a whole lot to differentiate the plugins.

Multiple ‘things’ with the same name is confusing. That’s really very obvious isn’t it? That’s why companies spend hours and months fighting to protect their trademarked names. The name of a ‘thing’ is important, and the difference between the names is the crux of everything. In a predominantly text world, your name is everything.

Bad Feelings

This is where it gets weird. As you all know, I’m a huge supporter of forking. But sometimes when you fork, you’re a dick. There are a lot of weird things to consider when you fork, and for me, the first one is ‘Is the plugin I’m forking something you pay for?’ Generally speaking, if I’m even considering forking a for-pay plugin, I’ll try to start up a dialogue with the developers first, because I know that these people are trying to make a living, and I’m a dick if I take that away from them. Yes, GPL says I can do it anyway, but there’s the law and then there’s the community.

A lot of the time we tout the ‘spirt’ of GPL and I really hate that. We’re actually touting the cohesiveness of the community. That we know plugins are often free, but pay for support, or behind a pay wall, or a million other things. But. If you take away someone’s ability to make a living, you are a raging dick.

Strong words, but ones I firmly believe in. It’s no secret I’m not fond of the IncSub folks and their behind-a-paywall/yearly fee for plugins. My issue isn’t their code, however, or their prices, but their attitude. And while I don’t like them, I will support till my dying day their right to do it. And if someone logs in to their site, gets an account, downloads everything and then puts it up on their own site, well, I’ll support IncSub in kicking them while they’re down, because it’s just not nice.(This actually happened in November 2011.)

As Jane Wells put it:

The GPL does allow for redistribution of GPL code. You can even charge for it if you like. However, here at WordPress.org that sort of behavior is not encouraged or supported in our repo. If you redistribute, we expect to see modifications not available in the original. We show respect for the authors of GPL code by only promoting redistributions that are useful as new contributions through helpful modifications.

Which is why, when I forked the plugins I did, I made clear changes. Works on SSL now! Works on Multisite! And none were pay-for.

But what does ‘being nice’ have to do with this?

It Pays to Be Nice

WordPress’s strength is their community. It’s the people who dream and invent, and the GPL has given those people tremendous amounts of freedom to be creative and expressive. Where WordPress runs into problem is personality conflicts and clashes (even the smartest people can be assholes). And where you will see the most of those conflicts and clashes is when it comes to GPL and who has the ‘right’ to do whatever. (Second only to GPL is SEO.) Once you incur the ire of a community, your ‘cred’ drops amazingly. That’s why so many of us are accused of ‘drinking the Kool-Aid’ when we tout the GPL party line.

A quote in my comment ‘guidelines’ is from Lord Buckley, “If you know what to do and you don’t do it, there you bloody well are, aren’t you?” We all know the right things to do are to be good people. To respect each other and treat our fellow man with kindness. I don’t care what religion you are, or even if you worship the FSM. The only way we all get through this thing called life is to be decent people. Taking away someone’s source of income is rarely nice, and when you do it and say ‘I did this because it’s GPL and I can!’ then you’ve done it for the wrong reasons. Just because you can do something doesn’t mean you should. We all learned that as children, that just because I can throw a rock at Timmy’s head doesn’t mean I should.

Theft

When we get to college, many of us experiment, for the first time, with being able to walk away from things we don’t want to do, even though we should (like your classes). And many times, these young adult challenges, where we do the wrong thing, come with no serious repercussions, and we determine that it’s okay to break some rules. This curious attitude follows us into adult life. It’s okay to steal cable/music/movies because the companies that provide them make a lot of money, and the artist never sees it anyway, so we’re not hurting the people who really matter.

Taking someone’s product that is for sale, making a change and giving it away, is perfectly acceptable in the GPL. But that doesn’t make it right. That makes it legalized theft, and it will hurt your standing in the community. And that’s what people mean by the ‘spirit’ of GPL. You and me and everyone else who writes code or contributes are the spirit of GPL. And when you hurt one of us, you hurt us all.

Go ahead and fork plugins, it’s what makes WordPress, and any GPL product great. But when you fork, do it for the right reasons, and remember that the developer you’re forking from is a person too.

Treat them how you’d like to be treated.

9 April, 2012
Once GITten, Twice SVN
I’ve been putting off learning git. I’m lazy, svn works fine what what I need, and … oh. Look. MediaWiki switched to git. This is a problem for me, because I upgrade my MediaWiki install via svn. When it comes time for a new version, I just run something like svn sw http://svn.wikimedia.org/svnroot/mediawiki/tags/REL1_18_1/phase3/ ~/www/wiki/ and I’m off to the races. But now I have to git off my ass and learn it.

Before someone asks, I use svn to update my code because I like it better than wget-ting files, unzipping, and copying over. I can certainly do that, but I prefer svn. It runs fast, it lets me see what changed, and it’s easy for me to back out, just by switching back to the previous version. It never touches my personal files, and I’m happy. The more I looked at git, and how it works, I started to wonder if this was a practical idea for upkeep anymore.

Now, I actually like git for development when you’re working with a team. It’s great. So any posts about how I’m stupid for wanting to do this weird thing will just be deleted. Constructive or GTFO. The rest of this post details the journey of going from ‘This is what I do in svn, how do I replace it with git?’ The tl;dr of it is that I can’t.

What I want to do

I want to check out a specific branch (or tag) of code and upload it to a folder called ~/www/wiki/

That’s it.

The road…

First up, I have to install git on my server. Unlike SVN, which has been bog-standard on servers for a hog’s age, git is the new kid in town, and the odds are it’s not on your server. Thankfully, my host had note perfect directions on installing git on CentOS 5.(I’ll probably upgrade to CentOS 6 this summer, when my sites are less busy.)

Second I have to ‘install’ the git repository. This was weird. See, I’m used to svn, where you check out code, use ‘svn up’ to upgrade it, or ‘svn sw URL’ to switch to a new branch/tag. The official directions for gitting MediaWiki were: git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git

That doesn’t tell me what version I’m getting, and I only want the latest stable release. It was unclear at this point what this cloning did, but I was told over an over that I had to clone to get the version I wanted. Thankfully, git knows a lot of us are in the WTF world, and have a nice crash course for SVN users. Most important to me was this:

So git clone URL is svn co URL and that’s how I first installed MediaWiki. But… I know MediaWiki is working on a million versions and I’m not specifying one here. The git doc goes on to say that for git, you don’t need to know the version, you use the URL and it’ll pull the version named ‘master’ or ‘default.’ That basically means I’m checking out ‘trunk,’ to use an svn term. This is exactly what I do not want. I have no need for trunk, I want this special version.

After more reading I found git checkout --track -b branch origin/branch which they say is the same as svn switch url which is excellent. I can also use git checkout branch to check out the specific version I want!

I’m very used to SVN, where I can browse and poke around to see the tags, branches, and so on. When I go to https://gerrit.wikimedia.org however, all I see are the latest revisions. The directions said I should get the file /r/p/mediawiki/core.git which makes me presume that’s what tells git the version I’m checking out, but I can’t see that. I don’t like obfuscation when I’m checking out code. After some digging, I found the URL I wanted was https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git and that shows me the files, and their tags.

The tags were important for the command I wanted to run: git checkout tags/NAME where NAME is the tag. I want version 1.18.2, which is the latest stable, so I want to do is git clone -b tags/1.18.2 https://gerrit.wikimedia.org/r/p/mediawiki/core.git

I tried it with pulling a copy of 1.18.1, and it ended up pulling about 89 megs and put it in a subfolder called ‘core’. Oh and it told me it couldn’t fine tags/1.18.2 and used ‘HEAD’ instead, which put me on bleeding edge. It took a while to find something that looked a little better:
```
cd ~/www/wiki/
git init
git remote add -t REL1_18 -f origin https://gerrit.wikimedia.org/r/p/mediawiki/core.git
git checkout REL1_18
```
In theory, that would get me the latest and greatest of release 1.18, be that 1.18.1 or 1.18.2 and then, when 1.19 was released, I could switch over to that by doing this: git checkout REL1_19

It was time to test it! I pulled REL1_17 and … ran out of memory. Twice. fatal: Out of memory? mmap failed: Cannot allocate memory happened right after resolving deltas. Everyone said ‘You need more swap memory’ but when I looked, it was fine (not even using half). So that was when I said ‘screw it, I’ll go back to tarballs.’

Just as I hit that wall, some Twitter peeps stepped in to explain that, no matter what, I have to clone the whole archive first. I’m not really happy about it. I like SVN, since even when I switch, it’ll only update my changed files. I wanted to be able to do that in git without needing to pull down the whole repo, since I only use it to update, and not develop.

And that there is my one and only issue with git. It’s entirely for developers. Sometimes, some of us just want to pull down the latest version to play with, and not the bleeding edge. With git, I have to clone the repository, then export the version I want to play with. That’s not optimal for what I want to do. On the other hand, I totally get why it’s done that way. It’s akin to the basic svn check out, where I get all the branches and tags, only much much cleaner. And that’s cool! Smaller and leaner is fantastic.

And yet I’m not a developer in this instance. I don’t need, or want, the whole release, just a specific stable release. So now my workflow would be…

Install

On Git:(Of note, every time I try to run checkout I get “fatal: Out of memory, malloc failed (tried to allocate 1426604 bytes)” and I get the same thing when I try to archive. If I use the tool to change memory allocation, it also fails … out of memory. I’m taking this as a sign.)
```
mkdir ~/mediawiki/
cd mediawiki
git clone https://gerrit.wikimedia.org/r/p/mediawiki/core.git .
git checkout 1.18.1 -f
cp -R ./mediawiki /home/user/public_html/wiki/
```
On svn:
```
mkdir ~/www/wiki/
svn co http://svn.wikimedia.org/svnroot/mediawiki/tags/REL1_18_1/phase3/ ~/www/wiki/
```
Upgrading
On Git:
```
git pull /home/user/mediawiki/
git checkout 1.18.2 -f
cp -R ./mediawiki /home/user/public_html/wiki/
```
On svn:
```
svn sw http://svn.wikimedia.org/svnroot/mediawiki/tags/REL1_18_2/phase3/ ~/www/wiki/
```
You see how that’s much easier on svn?

Now, someone wanted to know why I like this. Pretend you’re trying to test the install. You often need to test a specific install version, say version 1.17.1, against some code to see how far back something was broken. Being able to quickly pull that, without coding any extra steps, is crucial to fast testing and deploying. The tool we use at my office required me to reverse engineer and script a way to do that with an ant script, and certainly I could script all that here. It’s not even that hard. But what’s one line in svn is three in git, on it’s best day, and you’re always pulling the latest and reverting back to the one you want, which seems a little silly.

Now, someone pointed out I could use this: git checkout-index -a --prefix=/home/user/public_html/wiki/ When I read the man page, it doesn’t say you can pick a tag/branch to push, though. If you have some advice on how to fix that, I’ll give it a shot, but I suspect my memory issues will block me.

I will be using git for a lot of things, but a fast way to update, spawn versions, and test will not be one. For development, however, I totally adore it.
23 March, 2012
Yourls
For a long time I’ve wanted short URLs for one of my sites. Finally I figured out a short URL, picked up the domain, and said “It would be great if I could redirect posts with this! But how?”

As it turned out, I was making a mental mountain out of a miniature molehill. I do that sometimes, get all caught up in a non-meaningful detail. This was easy, it wasn’t super complicated, and it was fast. On the scale of things where WordPress is the easiest (1) and MediaWiki is the hardest (8), this landed next to Zenphoto (4) and was about the same (3 or 4, depending on your skills). It requires more RTFM than WordPress, and I had to do some things manually.

Setting Up Your Domain

First buy the domain. This part is obvious, I hope. Since I’m on cPanel, I added my new domain as an addon domain to the master. This let me have the short domain (do4.us let’s say) hosted off the main domain.com site, without making a separate account. If I’d wanted to map a domain, I would have parked instead of addon-ing.

To add an addon domain in cPanel:
1. Enter the domain for the new addon domain into the New Domain Name field.
2. Enter the main FTP username for the addon domain in the Subdomain/Ftp Username field. You can use the one you use for the mani account if you want.
3. In the Document Root field, enter the directory that will contain the addon domain’s files.
4. Enter the password for the addon domain into the Password field.
  - Make sure you use a secure password.
  - You can have cPanel generate a secure pasword for you using the Generate Password feature.
5. Confirm the password in the Password (Again) field.
6. Click Add Domain
7. To add files to the addon domain’s home directory, click the File Manager link, or use FTP/SSH like normal people.
Once I did that, and DNS propagated, I was ready to go.

Installing the App

I decided to use Yourls for this, since my friends use it, and I know (in that internet way) the guys behind it. Hi, Ozh.

That said, their install doc was screwed up. For 1.5, it says to edit a file that apparently isn’t included in the build. That’s okay, since I just used SVN anyway. The directions are very much geeky. This is not a simple WordPress install.

What I did was first make a database domain_yourls and added my DB user account to it (I never use my domain FTP account). Then I ran an SVN checkout from googlecode to grab the files into the root of my add-on domain: svn checkout http://yourls.googlecode.com/svn/trunk/ .

After that, it’s the manual editing of the config file (the sample of which is not included in the 1.5 zip) and then I went to myurls.com/admin/ to finish setup. I had to grab the .htaccess file sample, since mine didn’t copy down (my own fault there).

Configuring the App

Install the YOURLS: WordPress to Twitter plugin. Even if you don’t plan on using the auto-tweet function, this is the easiest way to get your URLs made. The “hard part” here is setting up a Twitter ‘app’ for the first time. If you’ve done it before, it’s not terribly hard, but with all new things, it’s scary. Ozh’s directions are painless, thankfully, and then … you’re done. And you have your own Short URLS!

What’s Missing?

Two things, and neither are YOURLS fault!

1) Twitter doesn’t know that three different URLs (domain.com/postname, domain.com/?p=2 and do4.us/2 for example) are all the same URL. That means if you use those Twitter Rewteet buttons on posts, it doesn’t show up the same way, and the ‘count’ is off.

2) There isn’t an easy way to tell Jetpack to use my short URLs instead of my site’s full one. Edited to add: By this I mean only in the ShareDaddy links. Like the ‘tweet/email/facebook’ ones. Actual shortlinks work perfectly.

I suppose a third is ‘Damn it, Twitter, stop shortening a short URL!’ but that’s a different rant.

Should you do this?

I think so, but then again, I’m weird.

Read Also…

Otto – Using YOURLS with WordPress

Rev. Voodoo – How I Set up Vudu.me URL Shortener With Yourls
9 January, 2012
Supporting Open Sourced Clients

You’re hired to build a website and you decide that the best tool for the job is an open source application. So you install it, configure it, add in plugins, tweak the design, and make it a perfect site for your client. You explain how the CMS works, how they add pages, media, etc, and hand over the keys. Everyone’s happy.

Then a month or so later, the CMS releases an upgrade. Your client clicks the upgrade button (because most CMS tools have made that easy) and it installed, but now the site is broken. They contact you, complaining, and you end up spending hours of your time trying to calm them down, complaining to the CMS folks, and being grumpy.

And for a lot of you, this is your own damn fault.

I know a lot of website-building consultants, and I’m not saying this lightly. As a website builder, it’s incumbent on you, the person who installed the CMS, to make sure your clients understand the implications of that CMS, how upgrades work, and to arrange for support, just like you would for any vended product. Basically, if you don’t communicate and educate, you’ve done this to yourself.

Know This Is Not Different

Installing an Open Source product for a client is absolutely the same as installing a traditional, closed source, vended product. It certainly feels different, since there is a far more casual approach to a lot of things, but at the end of the day, your relationship with your client, and theirs with the software you install, is exactly the same, regardless of where the software came from and who wrote it.

A lot of companies worry about Open Source since it’s complicated and nigh impossible to sort out who you can sue if things go wrong. What happens if they vanish? What happens if it breaks? Really it’s not that different. If Microsoft went bankrupt today and closed all their doors, you’d still have everything you bought, but they’d be gone and you wouldn’t get any more help from them. Ditto Apple, and everyone else. In fact, it’s just as likely that a major Open Source app will vanish as it is a Closed Source, or bought out, or no longer supported. And at least with Open Source (and anything GPL’d), the code is mine to maintain as I see fit.

But really, installing a product is installing a product, and the work you do and the support you provide is the same.

Know Your Product

Never install a product you don’t know how to use. Personally, I never install a product I don’t use regularly (which is why I generally only install WordPress, and turn to Andrea if I need help with domain mapping plugins). My reason is that if you use a product, you know what you’re getting into, how it works, and preferably how to tweak it. Some of what you need to know about the product depends on how you plan to support it, but a good rule of thumb is that if you’re installing it for someone else, you either better be an advanced user of it, or know how to get answers, fast, without restoring to forum posts like “Help me ASAP! My client is down!” You’re a professional, you’re expected to learn to use your tools and act that way.

This doesn’t mean you have to know everything, but remember that your clients can use Google, and if they know your handle is ‘Ipstenu’ and they’re using WordPress, they just might search for “Ipstenu WordPress” to see what kind of person you are. So if they search for you and see you being snotty, or using l33t/IM speak in the forums, they might question your professionalism. But if they see you asking the questions they’ve asked of you, they may doubt you. A good idea is to be honest “I don’t know how to do that off the top of my head, so I’m going to research it and ask around.” Network. Ask your friends (you do have friends in your product’s community, right?) and keep in mind your visibility.

Know the Future

We can’t predict the future with any long-term accuracy, but we can prepare for it. If you choose to use a product, you need to know where it’s going. The day to find out about new features is not the release day, nor is it even the pre-release candidates or the betas! You need to be proactive, and keep in touch with the project, where it’s going, and how that impacts you. Every open source product allows for ‘nightly’ builds. These are the things you generally don’t want to run on production versions of websites, but that doesn’t mean you shouldn’t run them on your site. Install the nightly release on a server, set it up so it auto-upgrades every night (or if you use subversion, set up a pull every day or every x hours). Include some sample data, include all the plugins you use on your client sites, and test it at least every week.

Doing all that is a lot of why, which is why some people don’t offer ongoing support (more about that in a minute). Even so, the only way to know your product is to know it. If a product is important to your bottom line, then it’s imperative you know it well. Pay attention to what will and won’t be changing in the next version, and if possible, know why that’s happening, so if your client asks “But why?” you can answer.

This is where I feel Open Source has a clear advantage to closed source applications. Getting on the Microsoft Beta test list is harder than finding parking at the mall the weekend before Christmas. Getting on an Open Source beta test is about as easy as blinking. You can download and test all you want, every day, without asking special permissions.

Know What They Need

Before you go anywhere with a client, you need to ask them what kind of support they want. Are they going to pay you just to build the site, and then you walk away? Do they want to pay you a smaller fee per annum for support, a set fee for upgrades, or hire you at your normal rates to bail them out? Don’t let them drive your decision, though. You’re the one doing the work, and if you have zero interest in ongoing support, be upfront, tell them you’re just going to install it and they need to find other resources for help.

Don’t be a dick about it either, of course. Give them a list of people you know are good for help, some resources for the product, and maybe you can work out a deal with your friends. You get a small percentage of any client referred, for example, to your friend Bob who loves helping people dig themselves out of a hole.

Know What They Know

Any time you install software for someone else, you need to teach them. At the very basic level, they have to know how to use the product, otherwise you’ll get them emailing you new content to post for them. If you want to support that, great, but most people would rather not, so you explain how it’s used. Write up a very basic document for it, save it as a PDF, and include it in your deliverable. Update it when new versions come out and mail it to any client still on your list (i.e. the people who’re still paying you) or post it on your website for anyone to download.

Once your client knows how to do the basics on the site, go back to what level of support you’ve settled on. If they’re going to maintain the site themselves, you need to make sure they know the basics for that too! How to install a plugin, how to upgrade, and so on and so forth. This will make them appreciate you, and hopefully recommend your services to the next guy. Treat people well, it’ll come back to you.

For a product like Drupal, which doesn’t have a full-version upgrade as a one-click option, I usually tell people “Hire someone. It’s a pain.” Beyond that, however, you need to make sure they understand what new versions entail. A lot of people don’t know that WordPress considers a point release to be a major upgrade (i.e. going from 3.1 to 3.2 is a full new version of WP, but 3.2 to 3.2.1 is not). They need to understand that, so when they do upgrade, they know what they’re getting into and aren’t surprised by, say, a new admin menu.

This goes for plugins and themes as well as the basic product. Teach them how to edit themes the ‘right’ way. Explain that they may want to make a duplicate of their site to test upgrades on because, while most work just fine, you should CYA and so should they.

Know How To Communicate, Damnit!

Everything is built off of good relationships with your clients and the product. As we all know, the key to a good relationship is communication. If it’s not painfully obvious, you need to communicate clearly with both of them. Learn how to help non-techs, and learn how to report possible bugs to techs. Bridge the gap between the two, and learn how to translate, because sometimes that wild bug is from your client doing something no one predicted (it happens). You cannot exist in a vacuum, after all and no one’s a mind reader.

When you finish a project with a client, they should know exactly what to do to use the product, have directions on how to upgrade (or how to contact you), how to get help, and what to expect from you in the future. Clearly communicating these things will result in a happier experience for everyone. Or at least an opportunity to do the “I told you so” dance.

What Don’t You Know?

What are some of your tips and tricks for supporting your clients with open source products?

2 November, 2011