Beginning with WebGUI 7.8.x development will be conducted and tracked through Git rather than Subversion. The git repository is hosted on GitHub: http://github.com/plainblack/webgui
We realize not everyone is familiar with the use of Git. This page has a brief guide on how to check out and use Git. For more information, use the git help command or read the tutorials and manuals on the Git documentation page.
On Linux, git should be available from your package manager. If it is not, or if you are using a different operating system, binaries and source are available on the Git download page.
The first thing to do is to set some configuration options for git.
# User information
$ git config --global user.name 'Your Full Name'
$ git config --global user.email 'Your Email'
# https://github.com/account - click 'Global Git Config' for these values
# optional, but used by various downloadable utilities
$ git config --global github.user 'your github user'
$ git config --global github.token 'your github token'
# Colorize output
$ git config --global color.ui auto
# Friendlier remote tracking
# Uses rebase for pulls, creating a cleaner history
# what rebase does:
http://blog.woobling.org/2009/08/git-rebase-for-impatient.html
# why we want to use it for pulls:
http://blog.woobling.org/2009/05/git-rebase-considered-awesome.html
$ git config --global branch.autosetuprebase remote
# Safer pushing - only push current tracking branch by default
$ git config --global push.default tracking
# Convenient aliases
$ git config --global alias.st status
$ git config --global alias.ci commit
$ git config --global alias.cp cherry-pick
# tell git to ignore various temp/backup files. make adjustments here as needed for your platform.
# these are global across all repositories
$ git config --global core.excludesfile ~/.gitignore
$ echo '*.swp' >> ~/.gitignore
$ echo '*~' >> ~/.gitignore
$ echo '*.bak' >> ~/.gitignore
$ echo '*.orig' >> ~/.gitignore
$ echo '*.rej' >> ~/.gitignore
$ echo '.DS_Store' >> ~/.gitignore
After setting the configuration options, the next step is to clone the git repository. The command used depends on if you have contributor access to the repository. If you do have contributor access:
$ cd /data
$ git clone git@github.com:plainblack/webgui.git WebGUI
If you don't have contributor access:
$ cd /data
$ git clone git://github.com/plainblack/webgui.git WebGUI
This will download the entire WebGUI repository at its current state onto your computer. It will also checkout the current development branch, called 'master'. If you start without contributor access but later gain it, you can change the URL using the command:
$ git config remote.origin.url git@github.com:plainblack/webgui.git
Next, you can configure repository specific options.
$ cd WebGUI
# ensure info directory exists
$ mkdir .git/info
# ignore WebGUI config files
$ echo '/etc/*.conf' >> .git/info/exclude
# can add other patterns for files in the webgui directory to ignore
Once you have the clone, you can switch to other branches. The first time you use a branch, you need to create a local tracking branch:
$ git checkout -b webgui-7.7 origin/webgui-7.7
After you've created your tracking branch, you can switch between branches just by giving it the branch name.
$ git checkout master
$ git checkout webgui-7.7
A list of your branches is available with the 'git branch' command.
$ git branch
* master
webgui-7.7
$ git branch -a
* master
webgui-7.7
remotes/origin/DataTable
remotes/origin/HEAD -> origin/master
remotes/origin/WebGUI8
remotes/origin/crypt
remotes/origin/flux
remotes/origin/gh-pages
remotes/origin/master
remotes/origin/memcached
remotes/origin/template_usage
remotes/origin/thingy_defaultView_maxEntries
remotes/origin/webgui-7.5
remotes/origin/webgui-7.6
remotes/origin/webgui-7.7
Everytime someone changes the Git repository, a new commit is created. In order to make sure you have the latest revision of the codebase, use the git pull command.
$ cd /data/WebGUI
$ git pull
This will fetch available changes and update your working copy to the latest commit from the repository.
Now you've changed some code in your working copy, fixed any bugs you might have made, run the regression tests, and are ready to add your changes to WebGUI. In order to add your code to the repository, you must commit your changes using git commit, and push them to the server with git push.
$ cd /data/WebGUI
$ git commit -a
This will launch a text editor for you to add some comments about what you are committing, for example:
fix: Fixed a bug in Collaboration Systems where dates were not properly formatted
rfe: Added ability for user to configure how Collaboration System dates are formatted
Updated some documentation for WebGUI::Session::Date
At the bottom of the text editor window, you'll see a list of the files that have been added or changed in your new commit.
Next, you will push your changes to the server:
$ git push
This will push your changes to the server. If your local repository was not up to date, your push will be refused. In this case, you will need to run git pull to bring your copy up to date before trying tp push again.
If you do not have permission to commit to the repository, but still want to fix a bug or implement an RFE, you can help by submitting a patch. You can create patches in the unified diff format using git diff. Follow the steps above for getting ready to save your changes (make sure there are no bugs, run the regression tests), but instead of committing, do the following:
$ cd /data/WebGUI
$ git diff > patch.txt
You now have a unified diff at /data/WebGUI/patch.txt. You can apply this patch to other WebGUI instances by doing the following:
$ cd /data/WebGUI
$ patch -p1 < /data/WebGUI/patch.txt
Read man patch for more information on how to apply patches.
Find the revisions that you want to compare using git log or the GitHub interface. Use the following:
$ git diff 20c1942 0cbc4ee
There are a number of branches in the WebGUI repositiory. The 'master' branch is where all new development takes place. This the branch you would use if you are developing new features. There also branches stable version development. 'webgui-7.7' is the branch for 7.7 bugfixes. Other branches are feature branches for developing larger projects.
WRE Build files are at http://github.com/plainblack/wrebuild
You can review the revision log online via GitHub's interface. Visit http://github.com/plainblack/webgui; find the directory that you are interested in then click on "history" at the top right of the file listing to view changes made to the directory and subdirectories.
Keywords: Development git scm