The Process Overview
- Step 0 - Identifying a Potential Contribution
- Step 1, One, Uno, PRIMO - The JIRA Case
- Identify the Team
- Identify Community
- Identify Pentaho Team Member
- Work Together
- Eureka! Code! (or whatever)
- Or Not
- Line Up Tracking
- Contribution Review
- Check It In
- Update Tracking
- Contributor Attribution
Step 0 - Identifying a Potential Contribution
Contributions can enter this process from many different avenues. The most likely and the easiest to identify would be those contributors that send an email or post a thread in a forum stating they have code/documentation/translation/testing to contribute.
Some contributions may start as a discussion between the Community Leader or a Pentaho Developer and a potential contributor. For example, Pentaho asks community members to document the resources they have available to work with, and we use that information to match members up with projects that suit them. At the start, there is no contribution, just an offer to complete a task.
The Community Leader should be notified at the beginning of this process, as that person is responsible for tracking contributors and contributions in total.
If you are unsure whether to start the process as the result of interaction with the community, contact the Community Leader .
Step 1, One, Uno, PRIMO: The JIRA Case
All contributions and potential contributions MUST start with a JIRA case! Try to get the contributor to create it. If it's their first contribution, or if it's faster/easier, create the case for them, but point out that our process requires that they create a case in our case tracking system.
Identify the Team
With every contribution, a new team is formed. Just like when you are assigned a new feature as part of our development process, there is always a discussion that takes place between you and another dev teammate about design, implementation and the fantasy football standings. This same discussion should in some part occur with your community teammate.
A community member will be "assigned" to the case. This just alerts a Pentaho team member that there is community involved in the case, and who they are. This will also be used to later automatically identify contributors for attribution. The community member should be able to make edits and notes to the case, but not change status or assignment.
Identify Pentaho Team Member
A Pentaho team member will be assigned to the case. This is no different than how we manage all other prioritized JIRA cases. The big difference is that this will be a case in your bucket that most likely will not be prioritized for an upcoming release, although that is not always the case.
It is then up to the developer to communicate with the involved community member and facilitate progress on the case. This should not be a time-consuming, hand-holding exercise. It should be more about mentoring, defining requirements, getting the community person over humps and gaps that would be obstacles to anyone who doesn't sit next to a developer in our office regularly.
Regular action items during this step include but are not limited to:
- Email/forum post the community member to establish a relationship. You may have already been included on a thread introducing you to the person. Follow this up with a hello email/post.
- Provide high level guidance to the community person regarding the case you are working on. Do not become first line support for this person! Direct out of scope inquiries back to the forums, "where the entire community can benefit from the question and answers". Use common sense here: if it is a key contributor, a partner or is a small request, help them out.
- It's possible that what seemed like a small do-able case is really a larger effort, or we don't have the design clear enough for you to guide the person. STOP and talk with the Community Leader and/or the Development Team Manager at this point. We do not want to encourage the community to dive into CODING pieces of the platform that we have yet to get our hands around. Instead we can redirect their efforts to public design discussions and perhaps community requirements documentation rather than code.
- Regularly update the case, whether it looks like it is going to reach completion or not. Someone else will pick the case up at some time, and the work that was accomplished this go round need not be wasted. Examples of the information to capture would be:
- Design decisions made with the community member
- Bugs/enhancements that were identified or that block development.
- Attach any code or use cases sent to the community member.
Eureka! Code! (or whatever)
At this point , we hope to receive the code, documentation, bug report, whatever the contribution may be. We need to accept the donated resource through JIRA. This is critical in order for us to automate tracking and publishing attribution for contributors, as well as understanding the amount of tangible contributions we are receiving. When the contribution is a bug fix posted in the forum, or the contributor is ignorant to our process and emails it to a developer, we need to enter the contribution into JIRA ourselves, and assist the community by again pointing them to our process for future contributions.
Since this process is iterative, a single JIRA case can potentially have multiple attachments representing contributions. The attachments should have enough information submitted with them that the history of the submissions is evident, and justifies the contributions as being part of the same case.
More times than not, the contribution process will be started, but the community member doesn't come through. We never receive the contribution. This should be handled just like cases that are reprioritized in the normal course of the development cycle. Hopefully, the community member and developer have captured in the JIRA case all the valuable info regarding the work that has been done up until the point of abandonment (more on that in a moment). The developer, declaring the task abandoned, will mark the case as inactive. The case will remain assigned to the developer and the community member, until it is on the internal project roadmap as a priority, or the community picks it up again. This commonly will occur with a new community member needing to scratch the half-scratched itch.
So how do you know when to declare a community contribution effort abandoned? There are several clear and some fuzzy signs that the effort is going on hold indefinitely.
Clear Signs to Abandon the Task
- The community member emails you and tells you he no longer has the time / the motivation / the resources to complete the task.
- The community member sends you a "first draft" that doesn't even measure up to what your 4 year old could do in front of the keyboard.
- You send a motivating email to the community member inquiring about his/her progress, and it bounces.
Fuzzy Signs Signaling Abandonment
- Even though you've sent several encouraging emails, the community member never gets back to you. I would say 30 days without some sort of status info is cause for abandonment.
Line Up Tracking
The contributed resource has to ultimately be linked to the original JIRA case. Whether this is the same record in JIRA or two that we link, the goal is to be able to identify a number of things:
- Number of contributions
- Quality of contributions
- Where a particular case came from (internal/external)
- How a case was resolved (internal/external)
- Status of cases
Once the assigned Pentaho team member has received the contribution, it must be reviewed for quality, accuracy, and license or copyright issues. In the case of code contributions, they must be merged and tested. In any case, with every contribution you should ask and be able to answer positively the following questions:
- Copyright and License: Has this community member agreed to our Contribution Agreement? Are there any other copyright marks or license references on the contribution that may conflict with the agreement or the MPL? If there is, bring it to Richard or James' attention, and they can help you resolve each case.
- Quality: Is this a contribution that SHOULD make it into our product? Does the code conform to our standards? Is the documentation clear and well-written? While these questions are subjective given a lack of documented internal standards, you can use good judgement to determine whether something is just too effed to accept.
- Accuracy: Is the documentation correct? Does the code work?
Check It In
If the contribution passes muster, then you can check it in to SVN WITH THE JIRA CASE NUMBER REFERENCED IN THE COMMIT COMMENT.
Update the JIRA case appropriately, FLAGGING THE CASE AS AN ACCEPTED CONTRIBUTION. This facilitates the automated attribution.
Giving the contributor attribution in the release notes and on our web site can be automated from this process. In the short term, Community will be responsible for gaining permission and giving attribution to contributors.
The Pentaho team member needs to provide feedback to the community person. The following are some things that need to be included:
- Close the loop - let them know their contribution is in, we're grateful, and they can check it out of Subversion or get it in the next release.
- Ask them if they would like another project. If they do, direct them to Community. We can start the process from the beginning.