One of the greatest joys of my life has been working in Open Source. Why? First, I get to work on exactly what I want when I want. Software development is a creative process and working for someone else doesn’t always let me express myself. I need that. If my contributions are helpful, in line with the project’s goals, and are approved by my peers I can make a difference.
That brings me to the second thing I love about open source: The people. Every project is different but in the TomEE project, everyone is volunteering their efforts and time and they know you are doing the same, so no one is going to demonize you for mistakes. They will guide you when you need it. In addition, the people in the community are really welcoming and fun to know.
I want everyone to experience the kind of joy that I do when working on an open source project like TomEE. So I’m going to provide you with step-by-step guidance on how to join the TomEE community and make a difference – as a side benefit you’ll make some new friends in the process.
Let’s start this journey by getting the source code and joining the community mailing list.
Section 1: Getting the Source Code
You can’t really contribute your coding skills if you don’t have the source code, right? But contributing isn’t limited to writing code. There is documentation to improve, example apps to write, and many other things. There is something for everyone. But you really need the source code before you can do much of anything. Fortunately, it’s really easy.
1.1 Create an Account on GitHub
GitHub.com is a cloud service where most Java open source project store and collaborate on their code. If you do not have a GitHub.com account, you’ll need one but it costs nothing and takes just a few minutes. If you have an account already, then skip this step and jump straight to step number 2.
- Open your browser and go to GitHub.com.
If you have never created an account on GitHub you should see a page like this one.
As is the case with any web site or service all you need to create a free account is your email address, username, and password.
- Enter your email address, a username, and password and click on “Sign up for GitHub”.
Once that’s done you should see the “Welcome to GitHub” page.
After following a couple of more steps you should see the following screen asking you to confirm your email address.
- Open your email and click on the verification link.
When you successfully verify your account you’ll see the following screen where the projects you create and join will be listed – right now it’s empty because until now you didn’t have an account.
1.2 Fork the apache/tomee Project
If you want to contribute to the TomEE project you should first “Fork” the project to your own repository. When you create a “Fork” you are simply copying all of the code and files from the tics and information about Apache TomEE open source project to create your own copy of the TomEE project. The Fork allows you to play around with and modify the TomEE source code and documentation without accidentally changing the original project. In a future post, you will learn how to move your changes into the regular project.
To “Fork” a project you have to navigate to the project’s page. In the upper left corner of your GitHub page is a search box.
- Enter “apache tomee” into the search box and hit enter.
There are actually a number of TomEE open source projects. In addition to the main project, there are sub-projects that somehow add value to the main project but are kept separate. You’ll see a list of them in your search results.
We want the main project, which is titled “apache/tomee”. Don’t worry about the other projects, they are not important to you at this point.
- Click on the “apache/tomee” link.
You are now looking at the Apache TomEE project page.
There is a lot of information on this page, feel free to click around, but if you have not worked on open source or with Git or GitHub, a lot of it will not make sense to you yet. That’s fine. You don’t need to know everything to get started.
Note: The page provides statistics and information about all the contributions made by people (called “Commits”), various temporary or alternative versions (“Branches”), the number of times TomEE has put a stake in the ground and said this version works (“Releases”), the number of people who have contributed code or documentation to the project (“Contributors”), and other stuff that you can figure out later.
On the upper right-hand corner is the “Fork” button which will make a copy of all the TomEE files and put them into your own personal repository.
- Click on the “Fork” button.
GitHub really does all the work for you. It will crank away for a bit – usually a minute or less – and then present you with the following image.
Let’s take a look at this in more detail. Of particular importance here are the links in the upper left of the page.
The green arrow points to your copy of the TomEE open source project and the orange arrow points to the source of that copy; the original Apache TomEE project. You’ll always see this at the top of your TomEE repository which tells people where you got the code from and provides a convenient link to get back to the original project.
Your Fork of the project is identified by a combination of your GitHub username and the project name (<username>/tomee). In my case it is monson-haefel/tomee. Your project name will be similar but with your user name instead of mine. Let’s go see your copy of TomEE in all of its glory.
- Click on the “<username>/tomee” link pointed at by the green arrow.
As shown below, your project page looks a lot like the original apache/tomee project page with a lot of the same information about commits, branches, and so on.
As you make changes to your own copy, these data points will, of course, change. This is your copy of TomEE taken as a snapshot at the time you created the Fork.
Section 2: Setup Git and copy TomEE to your hard drive.
When you work on open source code, you use a copy of the code on your hard-drive. This process is called “Cloning” and it’s actually pretty easy to do. Most open source projects today use a program called Git to clone source code, get updates made by others, and to contribute their own code back to the project.
Git is really powerful so there is a lot of different commands you can use to do all kinds of things, but for this tutorial, you only need one command, the clone command. In future articles, you’ll learn some other commands.
2.1 Check that you have the Git program on your computer.
On Mac OS X navigate to or search for the “Terminal” and open that. At the command prompt type in the following to make sure you have the Git program.
- Type in the following command
$ git --versionas shown below.
$ $ git --version
The results of that command should show some version of the Git program similar to what is shown below.
$ $ git --version git version 2.20.1 $
The version I have is the latest at the time I checked, but your version may be newer or older. It doesn’t really matter right now because most versions will work the same when it comes to the command we need to use.
Note: If you don’t have Git installed on your Mac (this is unlikely because Mac comes with Git pre-installed) you will see something like “command not found”. Have no fear. You can install it yourself and there is an excellent article that I found that makes the process pretty easy. If you don’t have Git on your machine then go to this tutorial “Install Git on Mac” by Michael Galarnyk and when finished return to this tutorial and get started again on Section 2, Step 2.
2.2 Clone your Fork of the TomEE repository
Now that you know you have Git on your Mac you can proceed to cloning (copying) your personal Fork of the TomEE code to your machine.
Navigate to the Documents directory by entering $ cd Documents/ at the command prompt.
$ $ cd Documents/
If you want to clone the TomEE project into a different directory, that’s fine, but this tutorial will assume that it’s in the Documents directory.
Now it’s time to execute the clone command. The clone command takes the form of git clone <the repository url> The repository URL can be found on GitHub. Open your browser, go to GitHub, and navigate to your fork of the TomEE project (named <username>/TomEE). You want to make sure it’s your Fork and not the main repository. Substituting your username for mine it should look similar to the following.
The URL of your Fork can be found by clicking on the green “Clone or download” button (see the orange arrow in the screenshot above).
- Click on the green “Clone or download” button.
After you click on the “Clone or download” button a drop-down list will appear as shown below. You want to get a copy of the URL so just click on the clipboard icon to the right of the URL as shown here.
- Click on the clipboard icon
The URL pointing to your Fork of TomEE is now in your clipboard. You are going to use that in the Git clone command so go back to the Terminal app.
- Switch to the Terminal App where you navigated to the Documents directory
$ $ cd Documents/ $
In the Terminal window, go ahead and enter the following command $ git clone <the repository url> replacing the <the repository url> with the URL in your clipboard after the command clone.
- At the command line enter
$ git clonefollowed by a space and then past in the URL from your clipboard.
The command prompt will look similar to the one shown below.
$ $ cd Documents/ $ $ git clone https://github.com/monsonhaefel/tomee.git
After entering the above command and hitting the enter button the Git application will do some processing and when finished it should look similar to the following.
$ $ cd Documents/ $ $ git clone https://github.com/monsonhaefel/tomee.git Cloning into 'tomee' remote: Enumerating objects: 1, done. remote: Counting objects: 100% (1/1), done. remote: Total 313222 (delta 0), reused 0 (delta 0), pack—reused 313221 Receiving objects: 100% (313222/313222), 64.56 MiB | 7.07 MiB/s, done. Resolving deltas: 100% (146512/146512), done. Checking out files: 100% (7852/7852), done. $
If your command prompt looks like the one above, you’ve done it! You have successfully Forked the TomEE project and cloned your fork to your own machine. Cool!
- Open up your finder and navigate to the cloned TomEE project.
Now you can spend some time on your own machine looking around the source code. There is a lot to it because TomEE has been in development for over 4 years and much of its code is based OpenEJB which has been in development for 20 years as well as other projects.
In future posts, we will go into the directory structure in more detail but for now it’s good just to have it on your machine. Don’t expect to make out much from theses folders at this point. We are taking baby steps and this was a big one!
Section 3: Join the TomEE Community
Now that you have Forked the TomEE project and cloned it to your own machine, it’s time to introduce yourself to the TomEE community. Please do not feel like you have to have any better grasp of what is going on than what you’ve learned in this tutorial. The next tutorial will show you how to ask for tasks, how to navigate the directory structure of the project, and how to use JIRA – a task management software – to review assigned tasks.
Joining the community means getting on the TomEE mailing list. There are two mailing lists, one is for users who use TomEE as an application server and the other is the “Developer” mailing list where contributors, like you, talk about fixes and enhancements to the TomEE code, ask questions (even simple ones!), request and get task suggestions, and report on contributions to the code base. It’s a community so you should think of it as a place where you not only do your open source work but also where you find like-minded people and hopefully new friends.
3.1 Go to the TomEE Home Page
We’ve already written a tutorial on how to join the mailing lists so rather than repeat that here I’m going to show you how to find the TomEE Community page and open the “Contribution tips” where detailed instructions on joining the mailing list and introducing yourself, as well as some helpful advice, can be found.
- Open your browser and go to tomee.apache.org
At this time the landing page looks as follows but it will probably change over time. As long as you enter in the tomee.apache.org address in your browser you’ll end up at the right place no matter what it looks like.
In the screenshot above you can see a green arrow pointing at the “Community” page. That’s where you want to go to read the “Contribution tips” tutorial.
- Click on the “Community” menu item (see green arrow).
The community page should look as follows. Again it may change over time but the basic links will still be there.
The “Contributions tips” is where we want to go next but the other pages are also important. The “Contribution workflow” is kind of a whimsical flow diagram in the form of a Java code on how to participate as a developer. It’s more a reference and its meaning may be a bit opaque right now but as you learn the process in these tutorials it will make more sense.
The “Apache TomEE” link is a quick guide to finding the project, cloning the main repository, and building the project. The “This website” takes you back to the home page for TomEE and the “TomEE Wall of Flame” shows a list of people who have contributed to the project – hopefully, your name and mug shot will be added before too long!
- Click on the “Contributors tips” link.
The resulting page marks the end of this tutorial.
Follow the instructions for joining the mailing list and introducing yourself. Read the advice about being brave and starting small and look forward to a big hearty “Welcome” and becoming a part of the TomEE Community! We are happy to have you onboard!
Conclusion
This tutorial is the first in a short series about getting involved with the Apache TomEE open source project where you can learn tons, meet new friends and peers, and add some new skills to your toolbelt.
In tutorials that follow you’ll learn how to ask for and get assigned tasks, navigate the TomEE project, and contribute your own code to the project.
