Changing the xTuple core

 

The goal of this document is answer the question "How can I get a change into xTuple ERP?"

There are basically two ways to effectively make an impact on the xTuple core:

  1. Write the change yourself and contribute it back.
  2. Financially underwrite the change by sponsoring xTuple or an xTuple partner to write it.

The bulk of this topic is dedicated to the first option.  If you are interested in the second option, you simply need to contact xTuple directly so we can discuss the cost and viability of your request.  The majority of features added to the core are added as a result of sponsorship.  Sometimes, however, if a feature request is narrowly specialized we will recommend writing a custom extension instead, which xTuple can also do for you.  Also there are often times when enough users in the community demand a change that we take on a development because it simply should be done.

It is important, however, to emphasize that the two options listed above are the best way to ensure the change you want to see makes it into the software.  For an overview on what technologies are involved in making core changes, click here.

 

Why would I want to give away my hard work or something I've paid for to be written?

To a large extent the open source community is based on an altruistic principle that users aught to feel a moral obligation to "give back" to the user community as an exchange for the free software they have the privilege of using that has been underwritten by others. 

We, of course, work almost exclusively in the business world where altruism falls just short of being a dirty word.  From that stand point a more practical answer is it lowers your long term costs and risk.  If you contribute to a feature that makes it into the core product you hand off the responsibility of testing, documenting and maintaining that code to xTuple... forever.  If you think about it this is a tremendous deal because the cost of these things is generally greater than the cost of initial development.  If you are not in the software business ask yourself: "Do you really want to be in the software business and expend precious resources having to document and maintain your changes?"  If you are in the software business then ask yourself "Wouldn't you rather move on to the next interesting project rather than doing all the tedious maintenance and documentation you'll be roped into if you hold back your change as a one-off?" 

In addition to these cost considerations, we have endless anecdotal stories of customers who come to us with a legacy system that was heavily customized by a single individual.  That individual is gone and now nobody knows what they did or how they did it, and the system is so heavily modified it can no longer be upgraded.  Do you want to risk putting the future of your business in the hands of a single individual?  Contributing your code back to the core ensures your changes are professionally documented and maintained now and in the future.

As a point of reference of what is involved in software maintenance, as of this writing xTuple changes the code and documentation at a rate of about 30,000 lines a month.  Typically 80% of these changes are maintenance related.  Operating systems and other surrounding technologies change at an incredible clip whether we like and agree with these changes or not.  It's quite a bit to keep up with.

 

Testing the waters

The first thing you'll want to consider is posting an entry in the xTuple how-to and developer's forums.  There you can find out whether the functionality you are looking for is already in the product, or slated for development.  Sometimes functionality exists, and it's just a matter of figuring out how to turn it on.  If what you're looking for doesn't exist, the forums may also help you determine whether there are others folks interested in the same thing.  You may be able to partner with other xTuple users in an effort to either code or underwrite your change.

 

Stating your Intent

If it turns out you want to take on a core enhancement, we recommend you start by recording your feature on the issue tracker.  All development, including both bug fixes and features, are tracked there.  Create a new issue clearly describing what functionality you intend on adding and set the severity level as "patch."  Again, this lets other xTuple developers know that you intend on making a contribution, and provides an opportunity to get feedback on your idea.  Please do this before you even start writing any code, because the feedback loop can be critical to the process.  The last thing you'd want is to find after you spent 200 hours writing code is that it can't be accepted or that it has to be completely re-written because it conflicts with some other initiative under way.  xTuple will usually change the status from "New" to "Acknowledged" to acknowelege that we are aware of your initiative.

If the change you want to make is fairly extensive or invasive, you may be asked to provide a specification.  We create and track all of our specifications using a collaborative online process so other people can participate and give feedback. 

 

Submitting the code

We generally advise contributors to zip up the files containing code changes and attach the to the issue on the issue tracker, and change the status to "Confirmed."   xTuple will then review the code and, if everything looks okay, merge your changes into the code base on Source Forge.   It will be subsequently tested and documented xTuple development staff following this cycle:

  • We change the status to "Assigned" and an xTuple developer reviews and merges the code.
  • The developer changes the status to "Resolved," with resolution "Fixed" meaning the code has been completed and commited to the code base. The version number the change was applied in should be set at this time as well.
  • The feature/fix is reviewed by Quality Assurance and the status is changed to "Closed" if everything checks out.
    • If a problem is encountered, the status may be changed to "Feedback" or be "Assigned" to the original developer.
  • If documenation changes are required, the Doc Flag will be set to "True" flagging the documentation team to incorporate changes into the documentation.
  • The documentation team will set the Doc Flag to false when the documentation is complete.
Once users have demonstrated that they bascially know what they are doing by contributing patches for a couple bug fixes or features, we may ask whether they would like to have direct SVN commit access for code, which makes administration easier for both parties.  In this case, you would assign the feature as "Assigned" to yourself when you start writing the code, and commit it as you progress.

Learn more

Click on the following links to learn more developing the xTuple core: