The following tasks are the typical ones needed for the Testing and Tracker teams.
- Set up local Git repository (read only from trunk).
- Keep local repository updated with changes from trunk.
- Apply patches and pull requests.
- Option with branches.
- Option without branches.
- Reset files to unmodified state.
- Work with older versions.
Testing and Tracker Teams Work Flow
People who want to test Pending issues need to do the following. These same tasks apply to people who want to monitor the tracker and confirm Open issues.
- Create a local working copy of the Joomla trunk.
- Update this local copy with changes made to trunk.
- Apply proposed patches (from Confirmed issues) to trunk to see if they work correctly.
- Be able to restore the local copy to its unmodified state.
Testers may or may not wish to use Git branches in their testing work. For simple testing of one issue at a time, creating local branches is not necessary. For more complex testing or for testing multiple issues at a time, it is more convenient to create a local branch for each issue. Both approaches are documented here.
In some cases, it is important to identify when a bug or issue was first introduced. With Git it is easy to restore the local repository to a prior state (for example, to a point in time in the past) and test whether the issue was present in that version. This process is also documented here.
Create Local Read-Only Repository
Testers do not need to create a remote repository on Github. They can simply create a local clone of the CMS trunk on their local test machine. This clone will allow them to easily keep up with changes made to the CMS trunk.
The steps for this process are shown below, first using the command-line-interface (CLI) for Git and then using Eclipse and eGit.
- Navigate to your project root folder (for example,
- Enter command:
git clone git://github.com/joomla/joomla-cms.git. The system will work for a few minutes, copying the entire remote repository to your local system. When you are done, you will have a local copy of the Joomla CMS repository in the current directory, along with a git repository (in the .git subdirectory). Note that this URL points to the joomla-cms project on Github. This project becomes the remote origin for the local git repository. For example, the command
git remote -v will now list origin as follows:
git remote -v
origin git://github.com/joomla/joomla-cms.git (fetch)
origin git://github.com/joomla/joomla-cms.git (push)
- Clone joomla-cms repository using the read-only URL. In Repositories View, click the button "Clone a Git Repository and add to this View". This screen will show the following.
Select URI and click Next. The screen below will show.
- Enter the URI git://github.com/joomla/joomla-cms.git as shown above. Then click Next to see the screen below.
This will default to select all branches. Keep this default and click Next to show the screen below.
Click on Browse and browse to the desired root directory for the project (for example, c:\xampp\htdocs\joomla_development\joomla-cms). Then click Finish.
- In Eclipse, create new PHP project in same folder. It will give a warning that files exist in this folder (which is OK).
- In Eclipse, right-click on the project and select Team→Share to share the project. In the Share Project window, select Git and click Next. In the Configure Git Repository window, select "Use or create repository in parent folder of project" and click finish.
- Note that this creates a relationship between the local repository and the joomla-cms repository on Github. You can see this relationship by opening the Repositories View and expanding the Remotes tree as shown below.
- Clone joomla-cms repository using the read-only URL. Right-click on project folder ("tortoise-git" in this example) and select "Git Clone" as shown below.
- Enter the read-only URL and the desired project directory (again, "tortoise-git" in this example), as shown below.
- The system will work for a few minutes, showing progress in the Receiving objects window.
- When it is done, a success message will show as shown below.
Update Local Git Repository with Changes Made to Trunk
The first time you clone the Joomla CMS repository on Github, you will have the latest version of trunk. However, the trunk changes frequently, as bugs are fixed and new features added. This means that you need to keep your local repository up to date with these changes, for example each day when you start working.
- Make sure you are in the master branch of your local repository with this command:
git checkout master
- Pull changes from the origin (joomla-cms):
git pull origin
- If there are any changes, these will show. Otherwise, it will say "Already up to date."
- Check your status by entering: git status. The display should show:
$ git status
# On branch master
nothing to commit (working directory clean)
- Make sure you are on the master branch: Team→Switch To→master. (If you are already on master, the master branch will be grayed out.)
- Pull changes from origin. Right-click on the project in PHP Explorer and select Team→Pull.
- If there were changes made, you will see something like this.
Otherwise, you will see a message indicating that everything was up to date, like this.
- Make sure you are on the master branch by entering TortoiseGit→Switch/Checkout and selecting the "master" branch.
- Pull changes from origin. Right-click on the project folder, and select TortoiseGit→Pull as shown below.
- In Remote, select "origin" as shown below and press OK.
- The system will show a success message as follows.
Important Note About Patch File Format
There is a confusing aspect of working with patches between SVN, Eclipse, Git and the CLI. This has to do with the way files are referenced inside a patch. Most patches made with Eclipse and Git will have a leading "a/" and "b/" in front of the file names. For example, a standard Git patch will look like this:
diff --git a/components/com_content/controller.php b/components/com_content/controller.php
index 53cc63a..25cee76 100644
However, patches made with SVN or using the "--no-prefix" option in Git will omit the leading "a/" and "b/" and show in the following format:
diff --git components/com_content/controller.php components/com_content/controller.php
index 53cc63a..ba2de80 100644
Most patches will be in the first format. It is easy to apply patches in either format, but the exact commands are different. These are outlined below.
Apply Patches and Pull Requests Without Branches
This can be done either with or without using branches. If you want to work on one patch at a time (similar to the SVN work flow), you can follow this work flow without branches.
- To apply a Git format patch:
git apply <file>. For example:
git apply mypatchfile.patch.
- To apply an SVN format patch:
git apply -p0 <file>. For example:
git apply -p0 mypatchfile.patch.
At this point, the proposed code changes have been made to your Joomla files. Now you can test the proposed changes to see whether they work correctly.
To apply a Github pull request, add ".diff" to the end of the URL. This will display a Git-formatted patch file in your browser. Save this file to your local machine and use the command above to apply it.
- To apply a Git format patch: Team→Apply patch. The Patch input specification window will show. You can apply a patch from a file or by copying the patch to the clipboard.
- Click Next to show the Target Resource window. Select the PHP project to apply to patch and click Next.
- The Review Patch window will show. IMPORTANT: If the patch is in Git format, set "Ignore leading path elements" to 1. If the patch is in SVN format, this is not needed.
- At this point, if the patch will apply correctly, the files will show with a blue arrow as shown below.
Note: If a red "X" appears next to a file, it means the patch will apply correctly. Check the patch file format to make sure you have the right setting for this type. Also, make sure you haven't already applied the patch.
Apply Patches and Pull Requests Using Branches
In many cases, it can be easier to create a Git branch for each issue you are working on. This way you can be working on several issues at one time while keeping the code changes for each issue separated. Creating branches in Git is very easy. Here is the work flow for applying patches using branches.
- Create a new branch:
git branch issue-123 (creates a new branch called issue-123).
- Apply the patch as shown earlier.
- Commit the code change to the branch:
commit -a. Now git will open the editor you chose when you installed git. Enter the commit message in the first line of the editor and save and exit. (If you are unfamiliar with the editor, you can either change the editor or use Eclipse, which bypasses this step in the process.) The commit message should be something short that tells you what you did, for example "Applied patch 123.patch").
- At this point, the branch contains the modified version of the Joomla files for you to test. You can easily switch back to the standard files with the command:
git checkout master. To switch back to the modified version, use the command:
git checkout issue-123.
- Create a new branch: Team→Switch To→New Branch. The Create a new branch window will show. Enter the name of the branch and click on Finish.
- Apply the patch as shown earlier.
- Commit the code change: Team→Commit. The Commit Changes window will show. Enter the commit message as shown in the example below.At this point, you can review the code changes or simply press the Commit button to commit the changes.
- To switch back to master or any other branch, again use Team→Switch To and select master or the desired branch.
Restore to Unmodified State (Without Branches)
If you are not using branches, when you are done testing an issue, you will need to restore your programs to the original unmodified state. Note that this is not needed if you are using branches.
- Use this command to undo any file changes:
git reset –hard
- Use this command to delete any new files added by the patch:
git clean -f -d
- This removes added files and directories.
- Run the command: git status and make sure it says "nothing to commit (working directory clean)".
- Use this command to undo any file changes: Team→Reset to show the Reset window. Select "Hard" for the Reset type and click on Reset.
- To remove any new files added by a patch, simple navigate to the files and delete them.
Restore to Unmodified State With Branches
If you use branches, it is much easier to switch back to the unmodified programs. You simply change back to the master branch. Once you are done with an issue, you will likely want to delete the branch you created. Here are the commands for that.
- Change back to the master branch: git checkout master
- Delete the desired branch:
git branch -D issue-123 (where issue-123 is the branch name)
- Change back to the master branch: Team→Switch to→master.
- Delete the desired branch: Team→Advanced→Delete Branch and select the desired branch to delete.
Testing Older Versions of Trunk
At times, it is helpful to figure out which commit might have introduced a new issue. With Git it is easy to restore the code base to any point in time and then test whether an issue was present or not. Because this task is much easier to do with Eclipse, that is what is documented here.
- Open the History View: Team→Show in History. This will show a view similar to this:This view shows every commit to the CMS repository. To restore your local files to a prior time, right click on the desired row in the history view and select Checkout. Your local files will be changed to the state as of that commit. You can now test that version. To change to a different version, repeat this process. To change back to the master branch (the latest version), do Team→Switch to→Master.