The following tasks are the typical ones needed for the Testing and Tracker teams.
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.
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.
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.
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 -vwill 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)
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.
git checkout master
git pull origin
$ git status
# On branch master
nothing to commit (working directory clean)
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 --- a/components/com_content/controller.php +++ b/components/com_content/controller.php
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 --- components/com_content/controller.php +++ components/com_content/controller.php
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.
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.
git apply <file>. For example:
git apply mypatchfile.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.
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.
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.
git branch issue-123(creates a new branch called issue-123).
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").
git checkout master. To switch back to the modified version, use the command:
git checkout issue-123.
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.
git reset –hard
git clean -f -d
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.
git branch -D issue-123(where issue-123 is the branch name)
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.