Contribution Processing for Community Verifiers
As part of the Community Verifier program, members can optionally participate in a program designed to close the gap between making a contribution and actually getting the contribution into the Liferay codebase. This program will educate community developers, including community verifiers, on how contributions are taken into the codebase, using the resources that contributors and community verifiers are comfortable with.
What you will learn #
By participating in this program, you will:
- Get to know how contributions are made
- Meet and work with fellow members of the community, including Liferay core engineers
- Potentially learn new technologies like git, JIRA, and the underlying Liferay technology (which includes many technologies other than pure Java coding)
- Have fun!
- Make a difference by contributing your time and expertise to open source
The Process #
The basic process is to choose an existing contribution (either one developed by yourself, or more preferably one that you have not yet encountered). Make sure it is in "good shape" for inclusion into the code base, and then work with the appropriate core module owner to get it into Liferay. The specific steps are outlined below:
Step 0: Understand Liferay #
It is assumed you have a basic level of software engineering knowledge. Liferay is a large project, and you're not expected to understand 100% of the inner workings. But you should review the Contributing and Core Development Guidelines, as you will be working on contributions for Liferay. See step 2 below on who to contact for help in these areas if you are unfamiliar with them.
Step 1: Choose a contribution #
There have been many contributions made to Liferay over the last few years. All contributions usually start out as a JIRA ticket, and you can see the list of outstanding contributions. Some of these are recent, and some are quite old. And there may also be contributions lurking in the forums. But for now, we will concentrate on those JIRA tickets. Choose any contribution you like (including those that don't appear on the surface to actually be a real contribution, read below for more detail).
Step 2: Evaluate the state of the contribution #
The chosen contribution should be inspected. This includes:
- Understand if it really is a code contribution. It might be one of these:
- It is really just a bug report, without a real solution (but if you have an idea of how to fix it, then continue on to develop the fix yourself!).
- The submitter may have marked it as "Contributed Solution" for any reason, without really understanding what that meant, and in fact it is not a contribution at all.
- If it isn't a contribution, and can be closed or reassigned to a different state, add a comment stating the reasons and what needs to be done with the bug (close it, mark it as a bug, etc), and feel free to choose a different one (but keep in mind that this kind of cleanup is exactly what the Community Verifier program in general is about, so you can feel good that you have contributed with your evaluation!).
- Understand the motivation behind the contribution. Was it in response to a perceived bug? If so, take the time to understand the bug first. If it was a new feature or improvement, try to use Liferay in that area so you can experience the pain or lack of such a feature.
- Consider the age of the contribution. If it is old, then chances are it won't work "as-is" and will need to be massaged. And if it is really old, chances are the original contributor won't be around and you'll be on your own (sort of).
- Consider the Liferay release and environment (app server, OS, DB, etc) against which the original contribution was made.
Step 3: Get Help! #
- Attempt to contact the original contributor. You can click on the contributor's username on issues.liferay.com to get their email address, and send them email letting them know you're interested in working on their contribution with them as part of the Community Verifier program. Even if you feel you can handle the issue completely on your own, it is good to let them know you're working on it, in case they have additional detail or some update to their contribution. You may also want to establish other lines of communication, such as instant messaging, etc.
- Attempt to identify and contact the relevant module owner based on the area in which the contribution was made. If you don't know who to contact, please contact Juan Fernández or Drew Blessing and they will get you started down the right path! Getting in touch with the relevant Liferay Core Engineer will let them know who you are, and establish a line of communication for issues on down the road. They can assist you with the rest of the process.
- Join the #liferay IRC channel on freenode.net. Many Liferay developers and users hang out there, and may be able to help further. Plus, it's a great group to hang out with for general Liferay goodness.
Step 4: Evaluate the readiness of the contribution #
This step is probably the most time-consuming. You will need at a minimum a copy of the current Liferay source base, ideally using a fork of the liferay-portal and liferay-plugins source code on Github (see below for details on using git and Github). If you are not familiar with Github, it's not imperative that you learn how to use it, but it will help with the process later on when it comes time to integrate the contribution into Liferay. If you want to stick with raw text files, please do! It will not be held against you :)
Contributions are generally code fixes for Liferay, either in the form of full files representing the fix, or files that show the differences in the "old" and "new" code (sometimes just called patches or diffs). These contributions can take many forms:
- Patch (diff file) for existing Liferay core or plugins code
- Complete copy of one or more new or changed files, with modifications included, for existing Liferay core or plugins code
- A simple "one-liner" diff or correction to an old bit of code.
- An already-formed Github "Pull Request" containing the diffs
The first step is to see if the contribution is no longer needed. The contribution is no longer needed if:
- The feature area in which the contribution lies has been deprecated or removed from Liferay
- The contribution is a bugfix, and the bug has already been fixed in the latest Liferay trunk/master codebase
- The contribution is an improvement, and an identical or similar-enough improvement has already been made in the latest Liferay trunk/master codebase
Make sure you test the latest Liferay trunk/master to see if the contribution is no longer needed before continuing on. If it is no longer needed, add comments to the ticket and recommend its closure (you may also discover this by contacting the original contributor and/or Liferay core engineer, who may have knowledge of this already!).
Step 5: Massage the contribution as needed #
Next, if the contribution is relevant, then see if it works as-is (or with minor modification):
- Take your copy of the Liferay source, and apply the fix (either the patch diff or copy files in place) to the source. Does it apply cleanly with no errors? Chances are it will not, and minor modifications will be needed.
- Compile and deploy the fix (again, depending on the nature of the fix, this might mean many things). See if it fixes the bug or the improvement actually works. If it does, then you are well on your way.
- If things don't work out cleanly, you will need to work with the original submitter and/or Liferay core engineer to get the contribution into shape so that it cleanly applies to the latest Liferay trunk/master code.
- Ensure that the fix adheres to Liferay's coding standards. Here the Liferay core engineer can be an immense help, to do code reviews and other checks that might not be universally known about. You can also read up on the [Development Style] to get an idea of the expected format of line breaks, curly braces, and other minutiae of Liferay coding.
Step 6: Contribute the code! #
After working with the original submitter and Liferay core engineer, the contribution code should be ready for inclusion into Liferay. If you aren't using Git, you may work with the Liferay core engineer so that they can take it from there. If you are interested in using Git, then the next step is to issue a pull request, most likely to the Liferay core engineer who is the module owner of that area.
You're done! The Liferay core engineer will be able to properly denote in the ticket that the contribution is being actively worked on and/or is complete.