Joomla! Documentation™

Under Construction

Intro

This document will provide information about contributing to the Joomla! CMS with help of Git and GitHub. If you like to made a simple change (one file only), it is easier to use this documentation: Using the Github UI to Make Pull Requests If you like to add more complex changes or you're just interested in this, keep reading!

What are Git and GitHub?

Git is a distributed version control system. It is a system that records changes in files, and keep this changes in history. So you can always look back to an earlier version of you're code and restore changes if you like. Because of the history, Git is very useful when you work with many people together on the same project.

On this moment GitHub can be used. GitHub is an website, what helps manage Git Projects in a visual way. As owner of a project you can change the code, and compare different versions. As user of the project you can contribute by making an Pull Request. A Pull request is a request to pull some code in that project. You're offering a piece of code, what can be a solution for a bug for example, and asking if the Project owner(s) like to use it. If the owner likes it, he can merge (add) it to his project.

Joomla! uses GitHub and Git to maintain it's code. So everyone can contribute to Joomla! if they like to. The URL to the Joomla! CMS Project on GitHub is: https://github.com/joomla/joomla-cms

Getting Started

Sign up on GitHub and install Git

First, you will need to register at GitHub. It's free and very easy to do, just follow the provided steps.

One we are signed up, we need to install Git. The latest version of Git can be found on http://git-scm.com. Download and open the installer. Git is an CLI program, CLI mean Command Line Interface. At the begin this can be confusing and a little bit scared. There is no need for that, this document will lead you to the whole process.

If you're not an advanced user you can just run the installer and press the "next" button until the program will install. Git won't damage you're system, and later you can remove it just like other programs if you like too.

Once we installed Git, we open the program called "Git Bash", and a command line will be opened. We going to tell Git our name and email adres. Git will use this information when we contribute to a project. With the following commands we give Git that information:

git config --global user.name "Your name"
git config --global user.email youremail@mail.com

In the above commands, and all other commands given in this documentation, each line is a new command. So you type the fist line, presses enter and then type the second line and press enter.

We are now ready to use Git, and go farther with setting up our test installation

Setting up a test installation

For our test installation we need a program that can simulate a webserver. So we can install and run Joomla! on our computer. There are a lot of program witch can do that. For example MAMP or XAMPP. Download an install one of them.

After the installation of such a program (I use MAMP in this documentation), we going to install the latest version of Joomla!. In our case, the latest version of Joomla! is not the last stable release. The last version of Joomla! is the staging branch on GitHub. First, let me explain a little bit more about GitHub.

On GitHub you can find projects, so called Repositories. Inside a project you can made several version, such a version is called a Branch. Joomla! has the following branches:

• Staging: This branch contains the latest bug fixes and new features of Joomla!
• Master: This branch is the current stable version of Joomla!
• 2.5.x This branch contains the latest version of Joomla! 2.5
• 3.5-dev This branch contains the files for Joomla! 3.5, witch is not stable at the moment of writing

On our test location we going to use the Staging branch. But if we should use this branch directly we have problem. We can not modify this branch because we are not the owner of it. What we going to do, is making a copy of it, on GitHub this is called a Fork. We are the owner of that copy so we can modify it, and after modifying we compare our fork with the original project. At that moment we can make a Pull Request for the changes we made. More about that later in this documentation. You can Fork a branch by press the Fork button on the Joomla! CMS Github Repository. This button is located at the right top of the page.

After forking, we are going to install Joomla! on our local Web Server. Go to the folder were you can run files on you web server. Most of the program use a folder called htdocs. Once we are inside that folder, press the right mouse button an click on: "Git Bash Here". The command line will open for this location.

Type the following command to download the files form your Fork of the Joomla! CMS. Please replace username with the username you are using on GitHub.

git clone https://github.com/username/joomla-cms.git

Once Git is ready with cloning, you can close the Git command line. Go to the folder called "joomla-cms",right click on it and select again "Git Bash here". The command line will open for this location.

Because the staging version of Joomla! can change any moment, it is very useful to have the possibility for keeping our fork up-to-date. So where are going to add a remote for this project. Type the following command:

git remote add upstream https://github.com/joomla/joomla-cms.git

We now added a remote called "upstream". With the following command, Git will search for new contribution (commits) in the staging branch we don't have in our fork. If it found some, it will add them to our fork:

git pull upstream staging

The changes are now only made on our local fork.