First Steps with Gitorious and git

This file is intended for beginners with git.

A few details can be found at
http://wiki.centos.org/QaWiki/AutomatedTests/WritingTests/t_functional

Hopefully this file will answer the remaining questions

Git
---
Probably all available options on git can be found with "man git". Specific help on an option ie "git fetch" can be found with "git fetch --help"

Getting started with gitorious
------------------------------

First you need an account with gitorious:
https://gitorious.org/users/new
After registration you will receive an eMail to verify your eMail-Account. 

Afterwards you can login to gitorious

SSH-Keys
--------
If you intend to use SSH with git, you have to register your public key with gitorious. Go to  "Manage SSH keys" and then "Add SSH key". Copy the content of your key (home-directory/.ssh/id_rsa.pub or home-directory/.ssh/id_dsa.pub into the window and "Save".

Cloning t_functional
--------------------
At https://gitorious.org/testautomation/t_functional you will find the button "Clone repository". Next you will be asked for a name for your clone - pick a name at your descretion or use the suggestion. Klick "Clone repository" and you have your own copy of t_functional with an SSH-URL that looks something like this:
git@gitorious.org:<<username>>/testautomation/<<your clone-name>>.git.
The HTTPS URL looks something like this:
https://gitorious.org/<<usernamm>>/testautomation/<<your clone-name>>

To work
-------
To work with your copy, you have to create a local clone on your linux box.
"yum -y install git" should install all you need to use git.

Cloning:
"git clone <<SSH-URL>> <<destination-dir>>" will create a clone of your gitorious-repo on your local box. You will find your clone at <<destination-dir>>.
You should set at least two global settings:

git config --global user.name "your username"
git config --global user.email "your email"

All git operations work best if executed within your <<destination-dir>>.

Within the destination-dir you will find the folder .git. Go there and edit the config-file. Change your user-credentials and add:
[remote "upstream"]
	url = https://git.gitorious.org/testautomation/t_functional.git
	fetch = +refs/heads/*:refs/remotes/upstream/*
This allows you to update your clone from the t_functional-master in later steps.

Now to work with the test scripts :)
Lots of good hints to start with can be found ind doc/WritingTests and in the allready available scripts.

After you are satisfied with your work, it has to be commited.
New files will have to be added to git with "git add <<path-to-file/filename>>". You can also use "git add <<path-to-file/*>>".
A final "git commit --all" will open a vi-like editor. Please enter some comments regarding your changes. After exiting the vi your changes are commit.
Use "git push" to push theses changes to gitorious.

Merge request
-------------
Your push (or pushes) to git need to be merged with the t_functional master. This is done with the web-interface. On the webpage of your clone - something like https://gitorious.org/<<username>>/testautomation/<<your_clone>> - press the button "Request merge". Add some comments/notes, scroll down and select your commits up to the point you want to merge (you can keep the dropdown menues unchanged). "Create merge request" will do just that. On https://gitorious.org/testautomation/t_functional you will now find the number of "Merge requests" being increased by 1. Clicking on "Merge Requests" will show you all current and previous requests (possible states are Open, In Review and Closed).


Keeping in sync
---------------
With time your gitorious clone and your local copy will drift from the t_functional master (you work on your copy and others work on their copies/master, pushes/commits and merge request happen and so on). The best way to deal with this is to do a local merge of the current master and your local copy:
"git fetch upstream" will fetch the current master from gitorious.
"git merge upstream/master" will now merge your local copy with the previously fetched master. This effectively writes all master changes to your local copy.

If - for any reason - you are unable to sync your repos correctly, you can always delete your clone at gitorious and
create a new one.

Happy git'ing and testing!