You are currently on IBM Systems Media’s archival website. Click here to view our new website.

IBM i > DEVELOPER > GENERAL

How to Contribute to Open-Source Projects


In the last article, I introduced a new open-source project named “IBM i Dash,” a dashboard for IBM i written in Node.js. My hope is that the IBM i community can work to incrementally refine IBM i Dash to include more features. Adding code to an open-source project for the first time can be somewhat intimidating (it was to me). My aim with this article is to remove any hesitation you have in contributing to open source by conveying the necessary steps. After all, you can’t break anything that can easily be fixed!

First things first. You must have Git installed on IBM i so we can interact with the Bitbucket IBM i Dash Git repository. The OpenSourceBinaries page on YoungiProfessionals.com (YiPs) has a section titled “Perzl RPMs (newer)” that you can use to obtain many AIX binaries, including Git. AIX binaries many times work unchanged in PASE because PASE is essentially the AIX operating system using IBM i as its kernel. Follow the directions on YiPs to obtain and install the wwwperzl.sh script. Then, run the following commands to install Git on IBM i in the IFS:



$ ./wwwperzl.sh aix61 wget git-1.8.5.4
$ ./wwwperzl.sh aix61 rpm git-1.8.5.4

These two calls to script wwwperzl.sh will produce a lot of output back to the screen as it downloads and installs the necessary packages. The packages are installed into IFS directory /opt/freeware and the git binary is in /opt/freeware/bin. To keep from having to qualify the call to the git command, you should run the following command so the /opt/freeware/bin directory is searched when commands are entered. Think of this as being similar to ADDLIBLE.

$ export PATH=/opt/freeware/bin:$PATH

To confirm the git binary is available, we can use the which command, as shown. We could also use git --version, also shown.

$ which git
/opt/freeware/bin/git
$ git --version
git version 1.8.5.4

The last step to configuring Git is to specify two global Git variables, specifically user.name and user.email, as shown. These two variables will be used when you issue “commits” later on—the act of marking a version of code in history.

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

Now it’s time to make use of the newly installed Git on your IBM i. To do that, I’ll show you how the concepts of “forking” and “pull requests” work, enabling the community to collaborate in organized fashion.

First, you need to sign up for a free Bitbucket profile.

Next, navigate to bitbucket.org/litmis/ibmidash and select the “Fork” link on the left navigation, as shown in Figure 1.

In Figure 2, we see the “Fork” form. The process of “forking” means we are going to create an exact copy of the parent repository and place it within our personal profile to do with it what we want. Note the settings I’ve specified on this form and then select the “Fork repository” button.

You’ll be redirected to the newly created repository located within your profile, as shown in Figure 3. The next step is to get the code into your IBM i IFS. We use the git clone command to do this. However, first we need to obtain the repository URL by selecting the “Clone” link in the left navigation, as shown in Figure 3.

Go back to your PASE shell and paste the git clone command obtained from the browser in Figure 3. You should see output similar to the following:

$ git clone git@bitbucket.org:aaronbartell/ibmidash.git
Cloning into 'ibmidash'...
remote: Counting objects: 18, done.
remote: Compressing objects: 100% (17/17), done.
remote: Total 18 (delta 3), reused 0 (delta 0)
Receiving objects: 100% (18/18), done.
Resolving deltas: 100% (3/3), done.
Checking connectivity... done.

Use the cd (change directory) command to go into the ibmidash directory.

$ cd ibmidash

Now we can run git commands against this newly downloaded repository. One command I use frequently is git status to learn what (if anything) has been changed by me in this repository, as shown:

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

As we can see, there aren’t currently any changes. So, let’s open the README.md file and make a small non-detrimental change by adding your name to the list of people. Figure 4 shows me opening the README.md file using the joe editor from within an SSH session. The joe editor is also obtainable using the aforementioned wwwperzl.sh process. Any editor can be used to make changes to this text file. Side note: the .md file extension stands for “Markdown,“ a more concise way than HTML to mark content.

Running the git status command again will convey the README.md file has been modified, as shown:

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Changes not staged for commit:
 (use "git add <file>..." to update what will be committed)
 (use "git checkout -- <file>..." to discard changes in working directory)

       modified:   README.md

no changes added to commit (use "git add" and/or "git commit -a")

This is where a high-level understanding of Git comes in handy. I’ve found Roger Dudler’s Git Guide does a good job of this. After reading Roger’s guide, we now know the next step is to stage the changes for commit. The concept of staging is more or less tagging files to be included with the next commit. Following we see the git add command used to stage the README.md file.

$ git add README.md

Running git status again reveals README.md is ready to be committed, as shown:


$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

Changes to be committed:
 (use "git reset HEAD <file>..." to unstage)

       modified:   README.md

Next, we issue the git commit command with the -m option so we can add a message about the changes that took place, as shown. This will store a version of the entire repository as it existed at this point in time.

$ git commit -m 'Added Aaron Bartell to list of people'
[master e1f50a4] Added Aaron Bartell to list of people
1 file changed, 7 insertions(+), 1 deletion(-)

Note the git commit doesn’t place the code back on the server. This is where the “distributed“ concept of Git comes into play. You can work happily in the IBM i Git repository without needing a connection to Bitbucket until you’re ready to share your changes back to the central repository. Following, see the git push command sending the master branch to the origin server. Use the git remote -v command to display the servers attached to a Git repository.

$ git push origin master
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 442 bytes | 0 bytes/s, done.
Total 3 (delta 2), reused 0 (delta 0)
To git@bitbucket.org:aaronbartell/ibmidash.git
  0c996c5..e1f50a4  master -> master

Navigate to your fork of the ibmidash project to see whether the commit made it back to Bitbucket, as shown in Figure 5.

Next, we want to submit the change back to the parent project so it can be merged into the parent project’s code base. This is done using “pull requests” by clicking on the “Create pull request” link in the left navigation, as shown in Figure 6. Notice the list of commits that will be included in this pull request, which in this case is only one. Select the “Create pull request” button to finalize the process.

At this point your duties are done. Now it’s up to the parent repository owner (me in this case) to review all pull requests and select the “Merge” button to accept the changes, as shown in Figure 7. Notice how easy it is for the parent repository owner to see the changes that took place because of the green and red colored diff at the bottom of the page.

So that wasn’t so hard, was it?

Granted several steps are involved, but once Git is installed, then the iterative usage of git commands makes managing source code very efficient and simple.

Git is open source. Node.js is open source. It’s great that we’re able to capitalize on these open-source projects that originated on Linux machines. But what about when we have IBM i specific needs, like IBM i Dash? It’s unlikely members outside the IBM i community would contribute to IBM i Dash. That’s why I’m hoping many of you reading this article will make the effort to implement Git on your IBM i. Take some time to walk through the process of doing a fork and pull request with a simple change to the README.md file, as I’ve described. If nothing else you will have another skill to add to your resume.

Contact me directly with any questions you may have at

Aaron Bartell is Director of IBM i Innovation for Krengel Technology Inc. and an IBM Champion.



Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.



Advertisement

Advertisement

2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

Are You Multilingual?

Rational enables development in multiplatform environments

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters