My first pull request to Joomla! on Github
From Joomla! Documentation
Revision as of 18:52, 1 June 2013 by Wilsonge
- 1 A Pull Request ??
- 2 Installation
- 3 GitHub
- 4 Import your clone
- 5 New Project wizard
- 6 Finished
- 7 The upstream repository
- 8 Code away...
- 9 Create a feature branch
- 10 Change the code
- 11 Step 1 - Commit
- 12 Step 2 - Push
- 13 The Pull Request
- 14 Push the Button
- 15 Play
A Pull Request ??
So what the heck could be a "Pull Request" ? No, I bet it's not what you're thinking right now...
A Pull Request is the Git Jargon meaning "I will send a request to a project, to pull in some code changes / additions I have made to their code base"
Got it ? This is how we (including you) are going to contribute source code to the Joomla! code base.
It might look a bit scary at first (at least to me) but in the end it's pretty easy - "similar" to SVN, but a lot better.
Here is how it works:
The installation depends on the operating system you are using. If you use Linux, you may find the git software in your repository.
For example OpenSuSE offers a "pattern" named
git that provides the git core (required) as well as a set of tools like gitk, an e-mail interface, scripts to import source code from other version control systems like svn and others.
For this tutorial we have created a GitHub user named
jlover - a dude who loves J :)
Import your clone
Mr. JLover uses Linux and his Eclipse workspace is at
Before eGit 1.0 it was not possible to create or clone repositories right into your workspace. To make things easier we set the default repository folder to our workspace.
Let's start. Go to your workspace, right click inside the PHP explorer and select Import....
Select Git ⇒ Projects from Git
Click on Clone...
In the window that opens up, copy and paste the HTTP URL from your GitHub repository. The remaining fields will be auto filled.
Your may also want to supply your password but this is not required if you limit the write operations to the command line.
Select the branches you want to clone. The master branch is the point of truth.
Now choose where you want to save the files. We will save them in our workspace and modify the default name joomla-platform to my-joomla-platform.
Please remember this name, as we will use it later when we create our project in the same folder.
The files are being checked out. Sit back and watch patiently, or go for a cup of coffee ;)
Finished. Click Next >
New Project wizard
Select Use the New Project wizard and click Finish to start it (windows like..)
Select PHP ⇒ PHP Project
For the Project name enter the name of the repository you previously cloned. my-joola-platform in our example.
Observe the message beside the yellow triangle that appears when you finished inserting the Project name, telling you that the specified location already exists.
This is OK and expected.
Click Next > and include other libraries if required.
After you click Finish, the new project will be created in your workspace.
Welcome to the Joomla! platform.
The upstream repository
OK. So far you have a local "clone" of your GitHub repository which is a fork of the main Joomla! repository.
But what if the information in the main Joomla! repository changes ? Remember your fork (and your clone) are completely independent from the main repository. Fortunately git allows you to add multiple repositories to your "working copy" to track changes and merge them with your work.
We are going to add the main repository and call it upstream. To do this I use the console because I have not figured out yet how to do this in eclipse (@todo?)
cd /home/jlover/workspace/my-joomla-platform git remote add upstream git://github.com/joomla/joomla-platform.git
To „update“ your clone with the latest changes from the main repository use
git fetch upstream git merge upstream/master
This will fetch the changes from the upstream repository and merge the upstream/master branch into your current branch.
So what are you waiting for ? Go and fix this bug or implement this cool feature and give it back to the Joomla! project. It's as easy as clicking a button ;)
Let's create a simple patch file using Eclipse. We're going to add a comment line to a file that is really important to Joomla! and then create a pull request in GitHub to the Joomla! project.
So if the developers decide that your changes are worth being included into the code base, all they have to do is pushing a button and your name gets graved in stone (aka changelog) and the respective blame will show your name as the author for the lines of code you changed - Is this cute or what ?
Create a feature branch
Git provides a handy feature called Branches. The concept is somewhat similar to SVN but the handling is completely different. This feature is also known as cheap branching.
So if you plan to make more submissions or just to keep you master branch clean, you should create a new branch.
Unfortunately Eclipses branching concept seems to differ a bit from the original. So I use the command line also for branching operations. @todo?
The shortcut for creating and switching to a new branch is
checkout -b so we will create a new branch called
cd /home/jlover/workspace/my-joomla-platform git checkout -b first-test
Note that the tree has also changed in eclipse (maybe you need to refresh)
OK we can now change whatever we want without "polluting" our original repository. The disk space required to do this is minimal. That's what is meant by cheap...
Change the code
Let's open the file
libraries/joomla/application/application.php. and make a test change.
You really should feel a bit important right now doing changes to such an important Joomla! core file - do you ? ;).
Note that after you save the file, a dirty marker
> appears. You can change this in the configuration if you prefer the svn icon overlays.
That looks good. Now here comes another new concept if you are new to git: To get your changes to you repository on GitHub two steps are required:
Step 1 - Commit
This step will commit your changes to you local repository. You can do this from within eclipse selecting the file(s) or folders you want to include in the commit.
Right click you project and select Team ⇒ Commit...
In the window that opens enter a meaningfull commit message
After you press
Commit note that the dirty marker
> has disappeared.
You may add as many commits as you like locally before submitting it to the server.
Step 2 - Push
This step will submit your code to the GitHub server(s).
We do this from the command line @todo?
git push origin first-test
This will push your changes to
origin (your (jlovers) repository on GitHub) and create a new branch named
Done. Your changes are on the internet. Let's check out the GitHub site
A nice feature in eclipse is the history view
The Pull Request
At this point we are finally ready to do our pull request. Let's go to our repository, be sure that you are on the correct branch (you may change this later), and find the Pull Request button.
Push it softly, nothing will really happen yet ;)
On the next screen you should enter a meaningful message to the developers.
Pay attention to the text white on black that shows from and to which repository:branch you are going to send your pull request. By pushing the button Change Commits you may modify those values.
Here you can preview the changes you are proposing.
Push the Button
Thank you for your attention and in advance for your contribution(s) to the Joomla! project.
The Joomla! CMS actually is also moving to GitHub. To get you up and running (yes You who are not familiar with this git and GitHub stuff yet), a playground branch has been created to...imagine: Play.
So go on and play.
Thanks for your attention.