Authored by Corey Ballou


Dear Kohana, I Detest Your 3.x Website

I’ve got a bone to pick with the Kohana development team. I just wasted a couple hours out of my day adding functionality to their core Validate class only to find that the functionality had already been added in a future revision. All I was looking to do was pass parameters to a custom callback function. I had even documented the entire change and was looking to post a feature request with an included patch. I later came to realize that the version I was using, 3.0.3, was outdated to the point of lacking this seemingly trivial functionality that was included in 3.0.7. So bare with me while I rant on why your framework is losing in the popularity contest.

A quick update.

I would like to preface this article by stating that the Kohana team has been making strides in their 3.0.x branch by including a Unit Testing Module which wraps PHPUnit, looking to eventually achieve 100% code coverage. In doing so, they have promised to no longer push changes in minor versions (3.0.x) which will affect the API in any shape or form. With that being said, there is still the possibility of them updating the core API to make improvements and additions to calls. Thanks to zombor for the clarification.

Please make your version changes more apparent.

The thought of you pushing or merging substantial feature changes into your latest branch and not referencing them in an organized and easy to follow manner on your website bothers me. You have absolutely no idea how many times I’ve had to dive into system/ and modules/ to verify whether some feature is lacking or has been changed since a previous revision.

Redmine isn’t a substitute for posting feature updates.

I know you use Redmine diligently. I understand you’ve got your bug tracking on lock-down. This is no excuse, however, for providing lackluster documentation on recent changes to your core framework functionality in an easy to read manner. Your community is not solely comprised of your core development team. If I visit, I should be presented with the most recent core changes from version 3.x.x to 3.x.y and a link to past changes between revisions. The key word here is easy to read. I’m talking about an abridged version of updates to core files, including the basepath to the file in addition to the class::method() affected. This is not only for the benefit of the community, but a benefit to yourselves as well. I gaurantee you’ll get less bug reports and feature requests if you keep your community well-informed. You can’t just assume that somebody wants to dumpster dive in the closed issues garbage. The subject lines of most of the bug/feature/patch requests are not generally descriptive enough to warrant a user actually clicking to read through them.

Kohana was intended for rapid development.

With rapid development comes the expectation that there is easily followable documentation and examples. I, as well as your community, know this to not be the case. I was actually in favor of your 2.x documentation. There are gaping holes in your new documentation and I’m forced to scour the API Browser which is simply auto-generated from your core class phpdocs. I’ve seen the section on What Is Kohana? titled This Documentation Sucks! I don’t believe linking to the external unofficial wiki is the proper solution. It’s a clear indication that you have a problem on your hands. I would gladly help work on updating your documentation upon request.

Et tu, Brute?

With that being said, I’m still an avid Kohana 3 user and advocate. Take this rant with a grain of salt and view it as a constructive criticism. I eagerly await the day you decide to take your framework more seriously as an alternative to some of the more widely advocated frameworks and bulster up the documentation and website. I believe these two key factors are what hinder you from more widespread support and praise. What you really need is someone within your team to take on the roles and responsibilities of managing your documentation.

Author: Corey Ballou

Corey Ballou is the CEO of Whether you're a student, young professional, entrepreneur, startup, or small business, you can be up and online fast with your own custom domain, email, and webpage on POP. Corey is a professional PHP developer by trade, specializing in custom web applications development for startups, small businesses, and agencies. Follow Corey on Twitter @cballou.

  • Jeremy Bush

    We are aware of things lacking in our development/release process, and we are always working to improve them. We are still kind of in the middle of finalizing our new development/unit testing process in order to keep the code from breaking on us. This is the first part of our process change to make things more reliable.

    However, I *do* think that the redmine reports that we generate for each version can be useful as a general guideline on what changed in a specific version. Perhaps we need to change the title of the issue to be more clear, and then when we fix an issue, describe what happened in more detail than just linking to the github commit. I don’t see much value, however, in regurgitating basically what the redmine report will already give you. We used to do this and I stopped doing it because I was basically just copy pasting what came from redmine.

    • cballou


      Thanks for the insight regarding the post. I really do applaud the effort you guys put in and I know the debugging process is quite painstaking in it’s own right.

      I don’t believe there are necessarily problems with the Redmine reports themselves, but problems with sifting through them to find some information that should be fairly trivial. The reports are, in essence, a little too detailed and cover a number of issues and fixes which aren’t necessarily pertinent to what the majority of your users care about. Most users don’t necessarily need to know that you fixed bugs X, Y, and Z on your main page if they don’t inherently change a method’s initial intent or functionality. What they do need to know, however, is if you change a function’s parameters, return values, output, etc. Or perhaps if you deprecate a function or entire class in favor of a new method or class.

      Redmine is perfect for the nitty gritty details when a developer catches wind of an apparent bug in the system. It does not seem to function as a good solution for supplying a summary of updates to classes and methods which affect the developer’s ability making system calls.

      I hope this makes sense, as does my article. It’s purpose was to summarize what I believe to be some of the aspects that hinder Kohana’s growth as a framework. I can say I am in favor of a number of changes made in v3.x. While I’m at it, I might as well throw a request that you guys consider including the modules SwiftMailer and Message into your packaging system as they are two features I miss drastically from 2.x and took a little searching to find 3.x alternatives.

  • Jeremy Bush

    Oh, if you want to help with docs, you are welcome to 😉

    Hop into #kohana on if you want to talk about it.

    • cballou

      I’ll be in there as cballou this evening after 7:30.

  • Bob Bonfiield

    I couldn’t agree more here cballou. We’ve been using Kohana for about a year now. We started right around the time that the KO3 release was getting ready for a stable release, and we really wanted to jump on board with it then. We knew that KO2.3.4 was going to be the legacy release from the get-go, but we simply couldn’t justify using a framework with such horrible documentation — API browsers are handy, but they’re no substitute for well-written documentation. And honestly, I’m deeply saddened that, almost a year later, the docs site has barely improved.

    A lot of developers hate to write documentation. Fine, but Kohana isn’t some project where the docs can be lacking. If you want developers to jump on board or evangelize Kohana at their jobs, you need to have a usable and comprehensive docs site. Comparing the docs for RoR or Django against Kohana is a joke. Sure, they’re larger projects, but how are we supposed to adopt a framework for our business when the learning curve for new developers is so high?

    We’re going to continue using KO2.3.4 until KO3 hits some sort of truly mature release. IMHO, it seems like the development team needs to take this problem more serious.

  • Spyro

    You say you liked more the 2.x docs. But they turn it OFF today. Anyone knows why?

  • Ben

    Alternatively, you’re welcome to use another framework.

    I don’t know if this is the way you intended it to sound, but your sense of entitlement astounds me.

    These people have created something amazingly useful – and given it away free for you to use.

    • Corey Ballou

      I’m sorry my opinions offend you Ben. This is the internet; so take the ear-muffs off and prepare yourself for unfiltered biased opinions.

  • Jason Nathan

    I suppose documentation is a real tough job. The unofficial WIKI does a great job of “use case scenarios”.

    Just a little diversification of those use cases will be a great start… :)

    • Corey Ballou

      True indeed, Jason. I believe user supplied code examples in the Disqus comments is a great start as well.

  • Web Developer Rob

    I’ve had a really good look at Kohana and nearly started to use it over CodeIgniter. The main thing swaying my decision was the lack of Kohana documentation – yes everyone may not need it, but personally, as someone picking up a new framework a comprehensive doc is a must really.