GitHub Hints and Tips

Fabrik source code is stored in and managed by GitHub, a web-site based around the Git source-code control system. Git is a very powerful tool, but it is also fairly complex and has (in the experience of the author) quite a steep learning curve when you start to use it.

This wiki entry is designed to help you up this learning curve as easily and quickly as possible. Please feel free to add to or tweak this wiki entry with your own experiences.

Git and GitHub basics​

GitHub stores the Fabrik code base in a repository or "repo" - and you can create your own copy of this repo by forking or cloning it. (Cloning is effectively making a read-only copy, forking is making a copy which you can update yourself, and then request to the Fabrik developers that they pull a copy of your changes into the fabrik master copy.)

With GitHub you can fork a copy from the fabrik account into your own GitHub account, and then you can clone your own copy from the GitHub site onto your own computer.

Git branches are used to keep different lines of development separate from one another. Fabrik code is stored in two separate Git "branches" - Master (for F3.0) and Joomla3 (for F3.1).

We recommend that you use a new and separate branch of your own for each separate contribution that you are developing. You will need to make sure that you create your new branch based on the correct "base" branch for the version of Fabrik you are using.

Each branch holds the line-by-line changes specific to that branch, so multiple changes can be worked on by multiple people at the same time without risk of confusion, and Git can automatically merge branches which change different areas of the same file and can help resolve conflicts where changes are made to the same parts of the same file.

Getting started with GitHub​

The following sections will help you get started with GitHub and Git i.e. the instructions to get your GitHub / Git environment set-up.

http://www.github.com

http://help.github.com/articles/set-up-git

If you are running Windows, the GitHub for Windows application (which we will refer to from now on as GHfW) does a pretty good job of providing a friendly Windows interface for basic Git operations.

When you create a 'fork' of the Fabrik/fabrik project, you are creating your own 'respository' on GitHub which is an exact copy of Fabrik/fabrik at the time you fork the project. To do this, when you are logged into GitHub, go to https://github.com/Fabrik/fabrik and click the Fork button towards the top-right of the screen.

Then you clone it to your computer to get a local copy.

• If you are using GHfW, from the home screen select your userid under the "github" heading and then click "Clone" on the Fabrik/fabrik entry.
• If you are using the Git command line, then the instructions for creating a clone are here.

Creating a new Contribution​

To create a new contribution you will need to:

• Create a new branch based on the correct base branch (master for F3.0, joomla3 for F3.1)
• Edit files locally and Test your changes
• Add any new files to Git
• Create one or more commits of your changes
• Push your new branch from your local clone to your GitHub fork
• Create a Pull Request to the fabrik developers to review and then pull / merge your contribution into the main Fabrik code
• Respond to review comments by the Fabrik developers

In GHfW, go into your local clone, switch to the correct base branch (master or joomla3) and create a new branch by clicking on the base branch, typing into the text box and pressing enter.
In Git command line:

• "git checkout master" or "git checkout joomla3"
• "git checkout -b newbranch "

Use your favourite editor to edit the fabrik files you want to change.
For windows, you might want to take a look at Notepad++ as a great code editor which can help highlight php, xml, js syntax.

It goes without saying (but we are saying it anyway) that you need to unit test your changes before you commit them locally, and to test the entirety of your changes as a whole before you send them to the fabrik developers for review.

Remember to test that both your new functionality works as you want it to, and that your changes do not break existing functionality.

It can help your testing if you:

• Set Joomla Error Reporting to maximum (Joomla Administrator / Global Configuration / Server / Error Reporting = Maximum) to see php errors; and / or
• Turn on Fabrik Debugging on (see Troubleshooting tools); and / or
• Use the JDump joomla extension to dump variables to see what is happening inside your code.

If you are using GHfW, the Fabrik repos have been set up so that you have to manually add any new files (in order to minimise the risk of files being added accidentally). To add new files, you will need to use the Git shell / command line (even if you are using GHfW) - see example below.

If you are using Git command line, then you will need to tell Git of your changed files manually also.

You can create one or more commits in your new branch. At each commit, Git saves the changes you have made - and you can roll-back or rebase based on each of these commits.

Typically a contribution may consist of a number of different stages of development and it can help with code review to put each of these stages into a separate commit.

When you make a commit you can provide a short description (30 characters?) and a long description (several paragraphs) to describe what changes you have made etc.

Once you have completed developing and testing your code you need to:

• Push your committed changes from your local clone back to your GitHub fork - use the GitHub for Windows publish or sync links to do this, or use "git push" from the command line.
• Create a pull request
  • Go to the GitHub site (http://github.com/yourid/fabrik)
  • Switch to your new branch, and click on the Pull Request (singular) link and follow the instructions to create a PR. Note: If this is a F3.1 change (i.e. based on the joomla3 branch) you will need to click edit and change the base branch to joomla3 in order to get GitHub to tell you that your changes can be automatically merged.

An Example Editing & Contribution Procedure​

Suppose we want to tweak a template in Fabrik 3.1:

1. First we switch to the joomla3 branch:
   
   Code:

   git checkout joomla3

2. Then we create a new branch:
   
   Code:

   git branch -b tweak_form_template_bootstrap

3. Then we edit a file (say components/com_fabrik/views/list/tmpl/Bootstrap/default.php) and create a new file (say components/com_fabrik/views/list/tmpl/Bootstrap/default_footnote.php)
4. Now we add the new file:
   
   Code:

   git add -f  components/com_fabrik/views/list/tmpl/Bootstrap/default_footnote.php

   and (if not GitHib for Windows) the existing file:
   
   Code:

   git add  components/com_fabrik/views/list/tmpl/Bootstrap/default.php

5. And create a commit - if not GHfW:
   
   Code:

   git commit -m "Type your commit message here"

6. And push to GitHub - if not GHfW:
   
   Code:

   git push origin master

7. The next step is to notify Fabrik/fabrik that you have made some changes to some files and would like to contribute them to the project. To do this you send a 'Pull Request' from your GitHub repository (see https://help.github.com/articles/using-pull-requests).

Updating your fork / clone with the latest Fabrik/fabrik changes​

Whilst you have been developing your contribution, other users and the fabrik developers have been busy making other changes to fabrik. Obviously we don't want to delete the fork / clone we have already made (since these contain the contributions you have just developed), but we do want to integrate the latest changes that have been made to the main Fabrik repo.

Updating this is a three stage process:

1. Delete any of your own branches that have been merged into the main fabrik code.
2. Update the master and / or joomla3 branches from the main fabrik repo - and push these changes to your fork on GitHub
3. Update any of your own branches that have not yet been merged so that they are based on the latest code.

Go to your fabrik fork on the GitHub site, and look at your branches. Github will identify which branches are merged and which are not.

Use the GHfW delete icons (trash-can) from manage / Merge branches.

Run the following commands from the Git shell / command line:
This merges the latest versions of Fabrik/fabrik with your local repository and pushes them back up to your own fork on GitHub.

The process for basing your own unmerged branches on the newly updated master / joomla3 branches is as follows:

1. Get a list of local branches
2. For each branch, rebase the branch on the newly updated base.
3. Push the rebased branches to your GitHub fork.

To get a list of local branches:
For each unmerged contribution branch, you need to know which base branch this contribution is based from and then:
If you get merge errors because you have changed the same code in your contribution that someone else has changed in parallel, then you need to:

1. Edit the file with conflicts and decide what the code should look like in the conflicting area of the file. Look for lines which say "<<<<<<< HEAD"
2. Tell git you have done this:
   
   Code:

   git add filename

3. Continue with the rebase:
   
   Code:

    git rebase --continue

You may need to read the git documentation for more details on this. Good luck!!

Ask for help if you need it​

Anyone who has been through this learning curve themselves knows how daunting it can be - so if you need help, please do ask in the fabrik forums.