Monday, March 26, 2012 - 00:04
Written by

Last week I wrote a blog about technical debt (comparing it to keeping a kitchen in order). I got a lot of feedback - most of it constructive. I'm going to resist belabouring the whole metaphor & limit this blog to a quick summary of some of the discussion that came out of it.


It's about making it better

There is such a thing as code without technical debt. It is found in textbooks & outputs the words 'hello world'. Code that is actually used has technical debt. Technical debt is a natural by-product of writing code without unlimited resources & time. So, while addressing technical debt is a good thing - saying that CiviCRM has technical debt is like saying CiviCRM is software.


On the flipside, it's important to note that CiviCRM is a remarkable piece of software & it represents a remarkable commitment by the core team and others. Most of us take this for granted but when you start talking about what we can improve sometimes this needs to be re-iterated.


It's also worth noting that the core team and others do improve the code on an ongoing basis - this was obvious when noting that a number of things brought up in response to my post had already been addressed or were in the process of being addressed. Just this week a change was made to autoload CRM files & remove the need for many require_once statements.


It's about repayment-welcoming

We have many ongoing -mostly bad - jokes in the CiviCRM community & many of you will be familiar with our new verb 'to patch-welcome' someone. Patch-welcoming is pointing out to people that if they would like something improved they are welcome to submit a patch. But when it's done well patch-welcoming also includes giving people enough information that they know how to go about it. We need to encourage people to submit code improvements - but we need to help them with it too.


It's about standards

One of the big blockers to people contributing debt-free code, or reducing debt is having clear standards as to what the code conform to - it's like doing the dishes in someone else's house - do you leave them on the benchtop or put them away the wrong house. Often we are scared to tidy up code because we aren't sure whether the Core team will agree we are tidying it in the right direction. Discussion from my blog continued onto the forum and then after we were officially 'standards-welcomed' onto a wiki page. At this stage we are working on deciding what standards we should work towards. It also triggered me to write an API standard - the api standard is more mature than the others as it is pretty much documents what has previously been agreed in various discussions and we have already been actively working towards it.


I wasn't surprised to see how much coders care about a standard for spacing as the strict standard of drupal seems to gladden many coders hearts. However, I was surprised Lobo suggested we move to the drupal standard - mostly because I had thought we'd need to define a standard that was similar to what was in place. However, I can see many good reasons for that approach.


It's about funding


One of the difficulties with paying of technical debt is that we are often funded to write new features or patch bugs. However, many of the bugs arise in code that has become complex and difficult to understand. A key challenge is getting those people who use CiviCRM to direct some of their funds into preventative maintenance.


It's about doing it


What part can you help with?


Filed under


Hey Eileen:


Thanks for this whole initiative, and for the putting it in the right framework. It is important to patch-welcome new people, but it's also a kind of willful naivety to patch-welcome new folks on a complex issue, kind of like inviting someone to help clean up the kitchen, knowing full well there's a loose board that they're going to fall through. Which of course acts like a filter, so that the only people left on the project are the really smart, dedicated and/or persistent ones who aren't put off by such things.


So, though I'd love to work on a bunch of little things, I get discouraged that my contribution is going to be wasted, irrelevant, or just add to the technical debt. Which is why it's important not just to patch-welcome people, but to also have a strong and enabled gatekeeper to provide leadership about where it's all going. That's of course a delicate balance with the whole community-democratic-open source-willful developer mix that keeps all open source projects busy, but it's what I'd need to see before I put too much energy in here. I don't even need to agree with them, but I do need to see progress and authority, and I suspect I'm not the only one.


Conclusion: carry on vanguard, awesome work with the API. I've even got a few patches I'm ready to submit now.


One idea that comes regularly is to have a structure/incentive to make regular payment (not that MIH is necessarly one shot). We discussed different models (like drupal association, a "pro" subscription, a fee to get listed as a provider...).

So far, the concensus was that we, as a community, are too small to be worthwhile putting something like drupal association and that the "I will keep something only for my pay customers" isn't in the spirit of the project (or at least we haven't found the right "added value" that wouldn't sound like we are treating as second class users the free users).

The other thing is that "cleaning" shouldn't be seen as something to be done by someone else. Various social exeriments showed that if you can pay for a service, then you are 'buying out' and won't contribute in time. Ideally, we need something were I can pay AND still fill guilty and embebt and work too:)

This being said, having a MIH refactoring could help, but the cost is soo hight that it's very unlikely to get funded, we will need a lot of in kind and more people coding/documenting/testing...

I think the focus of a refactoring MIH should possibly be on small open ended recurring payments - aim to get 30 people putting in $20-$50 per month & build from there

I'll contribute time helping welcome people, document how to patch (I've already done so), and make financial contributions for maintainance, code 'housekeeping' and bug fixes (I've already done so).

I believe it's in the direct personal interest for all CiviCRM contractors/implementors/consultants (whatever we choose to call ourselves) to do the same thing, and I know many have helped a great deal.

I also suggest a 'CiviCRM maintainance, testing, and fixing' MIH be setup.  I'll contribute gladly.

I remember my patch-welcome.  My head was spinning from looking at the code already, I didn't understand what the heck was going on.   As a PHP coder I'm "so-so".   It was suggested I submit a patch.   Although I knew what a patch was, I had never created one in my whole life.  I didn't know how to make a patch much less submit one -  I couldn't find any documentation - I had to ask.  DGG helped me understand how it worked.   I think my first patch took me several hours.   It was a change to 2 lines of code.   A nod to Dave for the help, and I know new coders will have an easier time of it than I did.  Just sharing an amusing story.

There is also the "hook-welcome", which is when you say to someone simply "use hooks".  My reaction was "what's a hook?".   A lot of people, even 'techies' don't know.   The documentation is much better now, of course, and getting better.

We should document as well how to create a patch and assign it to the issue...

Another point is to get a unit test with it. That's a difficult balance to find between asking what the project needs and the difficulty of understanding unit tests & patch & the whole infrastructure when the fix is 2 lines.

Not sure what's the right answer, but deserves a chapter in the developer book



I did create some documentation on creating and submitting patches and commited the docs (as well as screenshots) to the book McAndrew is leading.

Indeed, didn't see the super useful addition, will refer to it often hopefully!