How to Contribute

Open Source delivers better products faster because of the strength of an active community - developers, testers, writers, implementers, and most of all users. No matter which 'er' you happen to be or what phase of implementation or evaluation you are in, you can make valuable contributions.

Here's your guide to submitting just about any contribution to the Pentaho project. If you don't find the answers you need here, please post your question to our forums, located at http://forums.pentaho.org.

Discussion Forums and JIRA - Our Links to the Community

As you read on, you'll discover there are two primary ways of making sure your contributions are reviewed in a timely fashion and recognized - through our Discussion Forums and by way of our issue and bug tracking system, JIRA.

Discussion Forums are the first line of communication, collaboration and support for the Pentaho community. Not only can you get direct responses from the Pentaho development team, but the rest of the community is there to provide additional input and feedback regarding your ideas for the platform. We do not suggest you report bugs or send contributions through the forums however, because they will tend to get lost amongst the many conversation threads that take place there.

All bug reports, code, and solution contributions are recorded and tracked through our JIRA issue and bug tracking system (thanks to the folks at Atlassian for the open source license!). You can find our JIRA system at http://jira.pentaho.org/ . JIRA provides the Pentaho community with access to valuable information like the status of a particular bug fix, prioritization of new features and enhancements, a long term roadmap for the platform and a place for the community to log issues and contributions.

Reporting a Bug

All bug reports are recorded and tracked through our JIRA issue and bug tracking system. You can find our JIRA system at http://jira.pentaho.org .

Before submitting a bug report to JIRA, be sure to search existing JIRA cases and our discussion forums for similar accounts of the behavior you are seeing. There's a good possibility that the bug may already be reported, in which case you can get a status update on when a fix may be available and possibly a work around for the time being. There's also a chance that the behavior is expected by design and you can get further clarification on how the product is designed to work.  Please do a thorough search of JIRA before submitting new issues.  In many cases you may be seeing a different symptom of a known bug.  Having duplicate JIRA cases wastes time and resources that could be spent on design and coding.   If you find that your bug has already been reported, you can vote for it to be moved higher in the priority list.

If, after serious digging, you don't find any record of the bug, then log the case in our JIRA system. You can browse all cases in all projects in JIRA, and should take the time to consider which project is the appropriate place for your case. You must be a registered user in order to log the problem. The registration process is quick and painless, and only needs to be done once. 

After you have logged in to JIRA, there are a few guidelines you should follow to get the best response to your case:

• Make sure you set the case type properly - for a bug, the type should be... well... "Bug".
• The 'summary' field in the case report is the first thing Pentaho developers see when reviewing submitted cases, so make that description short but precise. For instance, instead of describing your problem as 'Receiving exception when running a report', you might be a bit more precise: 'BIRT report exception [odaconsumer.CannotGetColumnCount] causes report to fail'.
• The 'environment' field gives you the opportunity to describe any unique factors in your system environment that could affect the case. For example, what JRE or SDK are you running? What operating system is the application running on? What application server are you using?
• When filling in the 'description' field of the case report, the more detail for a reproduction of the bug you can give us, the better chance we have of finding and fixing said bug. Include details such as what exactly went wrong, the steps you took to reproduce the error, and what you expected to happen.
• Be sure to set YOUR name as the Community Assignee. This will help us communicate with you regarding your case submissions, and give you credit for the work you submit.

Contributing Code

Of course, the best ideas and bug notifications come with that last note saying, "By the way, I already wrote the code - where would you like me to send it?" We rely on our community contributions of time and code (and we'll never turn down money or beer) to keep our commitment to deliver a quality business intelligence platform in the open source arena.

Unfortunately, we got tangled up with some open source lawyers early in process, and they convinced us that we need to have each contributor agree to a few rules when they decide to hop on the band wagon. As such, you are agreeing to this agreement when you decide to participate in our JIRA system.

The basic jist of the agreement is:

• You agree the code is yours to contribute; you didn't lift it off some dandy code snippet web site with a miniscule yet proprietary license agreement you conveniently overlooked;
• You agree not to come back later and expect give-backs, in intellectual or monetary form - or any other form for that matter;
• You are not beholden to the community as a support slave for your contribution and
• We are not guaranteeing we'll use your contribution in the end.

To read the finer points of the agreement, check out the lawyer's version on our web site.

If all the legal foreplay hasn't completely turned you off, then read on to find out how you can submit your code to the project.

Submitting Code

Bug fixes, new features and improvements are each types of cases in our JIRA system; use the type appropriate to your case. You can find our JIRA system at http://jira.pentaho.org .

You can browse all cases in all projects in JIRA, and should take the time to consider which project is the appropriate place for your case. You must be a registered user in order to submit a code contribution.
After you have logged in to JIRA, there are a few guidelines you should follow regarding code contributions:

• Make sure you set the case type properly - bug fix, new feature or improvement.
• The 'summary' field in the case report is the first thing Pentaho developers see when reviewing submitted cases, so make that description short but precise. If your contribution is a bug fix, and you know the JIRA case number for the bug, it would be good to include that case number in the summary.
• The 'environment' field should list any operating systems, JREs, JDKs application servers and other relevant environment factors that you tested your code under before submitting it.
• When filling in the 'description' field of the case report, the content will depend on the type of contribution you are submitting. If you are submitting a small bug fix, you COULD paste the code in the description field along with a detailed explanation of the bug, what file(s) are affected and how to test the fix. If you are submitting a significant bug fix (multiple files affected or many lines of code changes), an enhancement or a new feature, then the description field should contain a description of the fix\feature\improvement, detailed use case for the code and how to test it.
• Be sure to set YOUR name as the Community Assignee. This will help us communicate with you regarding your case submissions.

Once the case has been created (click the 'create' button), you will be taken to a page that will allow you to attach your code to the case. The link to 'attach file' is in the list on the left hand side. Attach your code following the simple instructions on the page, and you are all set.  After attaching code, send an email to communityconnection@pentaho.org and let us know that you submitted code and what the JIRA case was.  This will get the code submitted faster.

GitHub hosted projects and submitting code

GitHub comes with it's own built-in process for contributing to projects. Please follow the documentation out on GitHub to submit a "pull request" back to Pentaho GitHub Pull Request Doc.. Please include a link to your pull request in the Jira case instead of patch files or pasted code.

Solutions

We are always looking for new reference solutions to share with the community. As the contributions come in, we will post a library of submitted solutions on our web site so the community can benefit from each other's ideas. Solutions should be submitted through the new feature type case in our JIRA system. Complete the case as described for other code contributions, then attach your solution as an additional file to the case.

Submitting Your Ideas

Whether you are a developer who is implementing the platform or a business analyst who needs to solve a particular problem using it, your suggestions are valuable! We encourage any community member to share their needs with us, as long as they are related to business intelligence software and the problems addressed by BI .

Typically, an idea for a new feature or enhancement will be born out of a topic in one of our discussion forums. You can find an index of our forums at http://forums.pentaho.org. We encourage you to start a thread with your idea or solution in the forum that's appropriate. As ideas are fleshed out, a Pentaho team member will inevitably be a participant in the topic and may work with community members one on one to nail down architecture and coordinate multiple members' requirements. At this point, a JIRA case will be created, and your idea gets on the map!

The same advice applies here as with other contributions - there is a good chance that someone else may have already started a thread detailing your same idea , so look carefully through the forums and existing JIRA cases before starting a new one. If a thread has already been started, be sure to add your needs or comments to that thread. And, of course, the more detail you can give us, the more likely we are to see your 'vision'.

Contributing Documentation

We value any community member that's willing to help improve or add to our technical documentation as much as we value our code development community. Probably more, since we are not the best technical writers ourselves and suffer mind-numbing pain through each documentation exercise.

If you would like to contribute an improvement to our documentation, or submit a technical article, you can do so in the Pentaho Documentation Wiki.

Internationalized Contributions

The place to start with a language specific contribution is to look under our International Forums for the language you're interested in. Internationalization efforts are coordinated within these forums among the community members that are most experienced with each language.

Each international forum will have a moderator that works directly with a Pentaho team member to manage internationalized contributions, their packaging and deployment into mainstream distributions on SourceForge.net.

If you do not see a forum for your language of interest, be a pioneer! Contact communityconnection@pentaho.org and request a new forum be started - you could be credited with leading the effort.

Submitting Test Results

The Pentaho team is in the process of building an automated platform test suite and submission protocol because, well, frankly, it's a damn good idea. Until that suite is completed, if you are willing to contribute time and resources for quality assurance testing, please contact communityconnection@pentaho.org. We will send you a matrix spreadsheet where you identify the environment and test variables in play, and submit your results back to us.

Offering Your Time

If you happen to have a few spare hours a week (or month), we absolutely can help you put that time to good use? Heck, you don't even have to know how to code - we need testing, documentation, samples, the list is infinite. However if you are a coder, there is great satisfaction knowing that you are helping build a business intelligence platform that permits the entire world to have the BI they need.

If you want to get involved, have the time or resources to commit, and are not sure where to dig in, send an email to communityconnection@pentaho.org with a description of the resources you have and the commitment you can make and we will be happy to hook you up with a Pentaho team member to coordinate the best use of your time.

Snacks and Such

Any good community member knows a decent meal (or even a handful of corn chips) goes a long way toward increasing developer productivity. Well, it at least improves their outlook anyway?

If you would like to submit a contribution of beer, snacks, soda, beer, chocolate, pizza or pretty much anything else edible (like beer), send your package to:

Pentaho Corporation
5950 Hazeltine National Drive, Suite #340
Orlando, FL 32822

Gifts and Other Acts of Bribery

While we do not condone frivolous gifts or taking bribes, we are not above such gestures either. If there is a certain body of work that, when completed, makes your life easier, and you have a small yacht surprisingly available for a weekend, we can definitely talk. Contact communityconnection@pentaho.org with your offer, and we can surely find SOMEONE, a Pentaho team member or a community member, that can help you out!