This is the second installment in a two-part article covering the Process Task portion of the Contribution Workflow. The Contribution Workflow is covered in detail in the first part within “Section 1: The Contribution Workflow Overview.”
The Process Task portion of the Contribution Workflow is where you do the work on an issue (bug fixes, enhancements, tests, documentation) after getting assigned a JIRA ticket. This is where the rubber meets the road; where the actual work of writing or coding a solution takes place.
The following diagram shows how the Process Task portion of the Contribution Workflow fits into the whole.
The first part in this two-part article covered steps 1 and 2 in the Process Task, specifically “Fork, Clone, Branch” and “Mark Issue IN PROGRESS”. This article picks up right where the first article left off covering step 3, “Ask Questions & Respond to Comments” and then steps 4 and 5 completing the discussion of the Process Task part of the Contribution Workflow.
2.3 Ask Questions and Respond to Comments
At this point, you should have forked, cloned, and branched as well as upstream fetched the TomEE project and marked the JIRA ticket as “IN PROGRESS”. You are now ready to review the issue in more detail and ask questions. The position of this step relative to everything else in the Contribution Workflow is shown in the following illustration.
Don’t be afraid to ask about anything that confuses you, and if you are new to open source or the TomEE project, you are probably encountering a lot of things that don’t make sense at first. We understand. We’ve all been there, so ask any question you want and someone else in the community will be there to help.
Questions are usually asked on the Apache TomEE mailing list. If you have not joined the list yet then read “Section 3: Join the TomEE Community” from the article “It’s Easy! Get the TomEE Source Code and Join the Community”. It explains in detail how to join the list and introduce yourself.
This step is actually not fixed. Asking questions is something you are always encouraged to do, so when in doubt don’t assume, ask. Some things you can figure out for yourself and some things you just can’t. Either way, the TomEE community is available to help.
2.4 Work on Issue
As the name of the step suggests, this is where you do your work; where you fix bugs, add enhancements, and update documentation.
Whether you are making minor changes to documentation or big changes to code, the process of doing the work is the same. You want to frequently fetch code from the Apache TomEE project upstream to ensure you are not creating conflicts and you want to commit your work and push it to your branch on GitHub. Here is a diagram that shows these steps which are discussed in detail next.
2.4.1 Checkout
This is not in the workflow shown above but it’s needed before you start work on any code or documentation. Remember there are two branches on your machine right now, the master branch which is your clone of the Fork you created, and your JIRA specific branch (e.g. TOMEE-2496). You want to be operating out of your JIRA specific branch. You can check which branch you are currently operating out of by executing the “branch” command as follows.
$ git branch TOMES-2496 * master $
In the above command-line, the branch command shows that there are two branches on my hard drive, “TOMEE-2496” (my JIRA branch), and “master”. The “master” branch has an asterisk which means it’s the branch I’m in currently. I want to be in my JIRA branch so I’ll need to leave the “master” branch and enter the “TOMEE-2496” branch. I can do that by executing a Git checkout as shown below.
$ git checkout TOMES-2496 Switched to branch .TOMEE-2496. Your branch is up to date with .origin/TOMEE-2496.. $
In the above console, the checkout command is highlighted and the results show that I have switched to my JIRA ticket branch, “TOMEE-2496”. With that done I’m ready to fetch an update from upstream and then do some work.
2.4.2 Fetch
Before you begin work each day you should do a Git “fetch” command from your upstream connection to the main Apache TomEE git repository.
Note: To learn how to set up your upstream connection see section “2.1.4 Git Upstream Configuration” section in the first part of this article. Once the upstream is established you can do an upstream fetch as explained in the section “2.1.5 Git Fetch upstream” also from the first part part of this article.
Below is the console showing the execution and output of the “fetch” command.
$ git fetch upstream remote: Enumerating objects: 21, done. remote: Counting objects: 100% (21/21), done. remote: Compressing objects: 100% (7/7), done. remote: Total 21 (delta 8), reused 20 (delta 8), pack—reused 0 Unpacking objects: 100% (21/21), done. From https://github.com/apache/tomee 8abdb1850f..e58ff848a3 master —> upstream/master $
Now that I know I’m in the JIRA ticket branch (e.g. TOMEE-2496) that I want and that the branch is up-to-date with Apache/TomEE I’m ready to do some actual work.
2.4.2 Work
With your local branch of Apache TomEE up to date you are ready to start making changes.
There are essentially two types of artifacts that you will be modifying when making contributions to the TomEE project: Code and Documentation. While the Git commands used to apply changes to Code and Documentation are the same, the tools used to actually make modifications to your local branch on your hard drive will be different.
2.4.2.1 Modifying Code
Although it’s not mentioned explicitly in the “Process Task” portion of the Contribution Workflow, at some point you are going to want to edit the code and run the tests, right? If you use an IDE like Eclipse or IntelliJ you will need to import the TomEE project into your IDE so you can edit, debug, and run unit tests. If you have a lot of experience with your chosen IDE this step might be obvious and you can skip ahead, but if you have Eclipse or IntelliJ you might want to read one of the “It’s Easy!” articles that explain how to import the code so you can work on it.
If the Eclipse IDE is your tool of choice read the article, “It’s Easy! Remote Debugging with Eclipse and TomEE”. If its IntelliJ you prefer, then you can read the article “It’s Easy! Debugging with IntelliJ and TomEE”. If you use NetBeans, Emacs, vi or something else you’ll have to try and figure out on your own for now. Once you do, please consider contributing that information back to the community! The more IDE’s we can cover the better!
2.4.2.2 Modifying Documentation
There are two primary forms of documentation used on the TomEE project, README.adoc files and the Web site. The README.adoc files are stored in the same repository as the code. We use the AsciiDoc format for our readme files. It’s not a complicated markup language but you’ll need to know it or reference it while updating readme files. Here is an excellent resource that shows how to use the AsciiDoc markup language. Use that or a similar resource when updating README.dot files.
If it is the TomEE web site you wish to work on than the article “How to Contribute to the TomEE Website” by Cesar Hernandez provides excellent guidance and advice on contributing to that effort. Contributing to the quality of the TomEE web site can make a huge difference in the lives of those using the software.
2.4.2.3 Things to Avoid
When you are making changes to code or documentation you want to be respectful of the work already done and to the other members of the community. This mostly means using common sense, but in an article on the TomEE community has some specific advice worth mentioning. Here are those tips verbatim.
Huge patches
Huge patches are hard to digest. Try to avoid them whenever possible. Any step forward is a good one. Small steps allow people to see where you’re headed and give input. That’s true regardless if you are a committer or contributor.
Be careful with reformatting
Try to never mix logic changes with code reformatting. It makes it nearly impossible for others to see what the actual change was. If you are a committer and want to reformat something, do the reformat as a separate commit before or after the real change. As long as they are separate and clearly marked it should be easy for people to see what is going on. If you are a contributor and want to reformat something, maybe suggest it on the list, but avoid submitting patches that are just reformatting.
2.4.3 Set Your Commit Identity
This is another set of commands that you are not explicitly called out in the flow diagram above but are needed before you make your first commit to the code.
You want to make sure that your commits are recorded with the right name and email address. By default, it will be recorded with a name derived from your computer which is probably not what you want. To ensure the settings match what you want you can edit them by executing two commands $ git config --global user.name “<your name>” and $ git config -global user.email <[email protected]> Below is a console showing these command with my own setting. You will want to replace the name with your full name and the email address with the same email address you use with GitHub.
$ git config --global user.name "Richard Monson—Haefel" $ git config --global user.email [email protected] $
2.4.4 Commit
When you do a Git commit you are essentially saving the work you’ve done and saying, “Ok. This work is finished and is ready to be saved.” It also serves as a snapshot of the entire project showing exactly what changes were preserved at the time the commit was executed.
Before you do a commit and save your changes, it can be useful to see exactly what you are going to commit. Do do that you can always execute a Git status command as shown below.
$ git status
On branch TOMEE-2496
Your branch is up to date with .origin/TOMEE-2496..
Changes not staged for commit:
(use "git add ..." to update what will be committed)
(use "git checkout -- ..." to discard changes in working directory)
modified: examples/access-timeout/README.adoc
no changes added to commit (use .git add" and/or .git commit -a")
$
As you can see the lines that starts with “modified” tells me exactly which file I edited. If I’m sure that is what I want to commit I can execute the Git commit as shown below.
$ git commit –am "Fixed a minor grammar error" [TOMEE-2496 1547b5d792] Fixed a minor grammar error 1 file changed, 1 insertion(+), 1 deletion(–) $
The -am is followed by a comment explaining what the change is and why you made it. This commit message should be clear, and succinct. Just enough information so it’s clear at a glance. This is useful for both yourself and others. The commit message is additional documentation that stays with the code for everyone to examine if needed in the future.
You can verify your commit by executing another $ git status command as shown below.
$ git status On branch TOMEE-2496 Your branch is ahead of .origin/TOMEE-2496. by 1 commit. (use .git push. to publish your local commits) nothing to commit, working tree clean $
As you can see the output from the status command shows the branch you are on and where that branch is relative to its copy on GitHub. In this case, the local branch is 1 commit ahead of the GitHub branch, meaning that there is a change on the local branch that is not yet reflected in the remote GitHub branch. You are now ready to “push” the commit to GitHub.
2.4.5 Push
A Git push command synchronizes changes on your local hard drive with the copy of the repository on GitHub. If there is no copy on GitHub then the push command will copy the branch up to GitHub and create a remote branch.
In this example, our local TOMEE-2496 branch has a change (“1 change ahead”) of TOMEE-2496 on GitHub, so we want to “push” the changes up to the cloud to preserve them.
$ git push Enumerating objects: 9, done. Counting objects: 100% (9/9), done. Delta compression using up to 4 threads Compressing objects: 100% (5/5), done. Writing objects: 100% (5/5), 454 bytes 1 454.00 KiB/s, done. Total 5 (delta 4), reused 0 (delta 0) remote: Resolving deltas: 100% (4/4), completed with 4 local objects. To https://github.com/monsonhaefel/tomee.git To https://github.com/monsonhaefel/tomee.git b8fa986ebe..1547b5d792 TOMEE-2496 —> TOMEE-2496 $
The output from the $ git push command tells you how many files were copied up to the branch on GitHub and that the push has succeeded. Your GitHubbranch is now in perfect sync with your local branch. If you are done you can either document your work thus far in the JIRA ticket or continue working on the problem following the Work process shown below.
2.5 Document Work in JIRA ticket
The fifth step in the Process Task portion of the Contribution Workflow is to Document your work in JIRA as highlighted below.
Writing enhancements and fixing code a big part of what open source is all about, but its also about collaboration. The reason open source exists and thrives is the crowdsourcing aspect of the industry, by which I mean the project is built by many hands from all over the world. Being a good open source contributor is as much about how you collaborate as it is about how you code.
To ensure that everyone understands what you are doing you need to document what you are working on and what you accomplished. This is done in the JIRA ticket in the description section.
If you are from China, you want someone from Africa to understand what you did and why. Don’t make them dig through your code when they are researching an issue related to your JIRA ticket. Help them out. We are all in this together.
Before you get started, the JIRA ticket, which you were assigned (see “It’s Easy! Your First TomEE Pull-Request: Using JIRA”), should already have a description of the issue as seen before work has begun. It might be as simple as describing a weird behavior and the steps to reproduce, or it might be more detailed even suggesting ways to fix the problem.
It’s your job to add to that documentation explaining the problem in more detail and what you did to address it. This type of documentation is added to the description section by clicking on the JIRA ticket’s “Edit” button as shown below.
After clicking the “Edit” button an editing dialog box, like the one below, pops up. This is where you make all your edits to the JIRA ticket including the description.
2.5.1 Explaining the issue in more detail
As you research the issue you are going to uncover a lot more information that was missed when originally reporting the issue. You might discover that the issue is caused by a bug in the code or by a configuration problem, or some incompatibility with a new API. Regardless, you should add to the documentation so that people know exactly what problem you are addressing.
2.5.2 What you did to fix the issue
While the phrase “the code is the documentation” sounds great and seems to relieve you of the obligation of actually explaining what you did and why, in practice code alone does not provide sufficent documentation on a project that dozens or tens of thousands of contributors are working on. The JIRA ticket is a great place to explain your solution and why you selected it.
This doesn’t mean that you have to show the exact code that you used, you can reference that by pointing to the class, method, configuration file or wherever you did your work. But you should explain how the solution you used addresses the problem. Explain your solution, some possible alternatives (if you think of any), and why you did the work the way you did. Short of reproducing the actual code, the more information you can provide to others who come after you the better. In most cases that will be at the time you submit your JIRA ticket for review, but someone might be reviewing your fixes months or years later because they had a similar problem or they are working on a part of the code that you modified in your JIRA solution.
You should be adding documentation to the issue throughout the period you work working on it. Don’t wait until the end to describe the problem in more detail. Edit the description as you go for better accuracy. This is especially helpful to you if you have a break between starting on an issue and solving it. It can be hard to remember at what point you left off or even what you were doing – don’t make it harder on yourself. Document as you go.
Conclusion
This concludes the two-part series on the Process Task part of the Contribution Workflow. With these two articles, you should have a detailed explanation of how to obtain the source code, do the work, and document it in JIRA.
After you finish working on the issue and feel that its ready to be reviewed you will move on to the next part of the Contribution Workflow, “Submit Changes” as shown on the left. An article covering this process will be published later, so if it’s not ready by the time you are, simply ask questions on the mailing list if the process isn’t clear. Remember, we are all in this together!
