Git migration docs

["Santi Béjar" <santi agolina net>]

Hi,

  as I wrote in http://live.gnome.org/GitMigration I would like to
help with the docs, so here you have the first one. It is based on the
Subversion page and does not explore new possible workflows. I'll
upload it as GitMigration/Git (first a copy of the SVN one and then
the modifications) some time in the future depending on the feedback.

Some notes and TODOs:
* The maintainer notes (== Final Steps ==) should be reworked heavily
and possibly move to its own page.
* Maybe we need an extra advanced document to describe more
complicated instructions ("git format-patch"/git am, git rebase, ...).

Santi

Here it is the document:

= Getting the most out of Git in GNOME =
== Introduction ==

Git is a powerful
method of allowing many developers to work on the
same source code. It is used extensively within the GNOME
project and often proves to be the first hurdle for new
developers that are attracted to the GNOME project.

See also [[TranslationProject/GitHowTo|How to use GNOME Git as a translator]].

Each developer clones a copy of the repository
of the source code from Git and then is able to work on
their own personal clone separately from other developers.
When they have made changes, they commit them locally. After they are
satisfied with their commits they push them back to
the Git repository.

The GNOME project has also set up [[http://git.gnome.org/|online
browsing]] of its Git repository.

If you would like to track the changes that occur in
various GNOME Git projects, subscribe to the
[[http://mail.gnome.org/mailman/listinfo/git-commits-list|git-commits-list]]
mailing list, a high volume, read-only list that receives mail every
time somebody
checks something into the repository. You can filter mail from this
list by the title of the
projects you are interested in.

== Getting Started ==

Before getting started, it is useful to remember a key point about
GNOME Git - it is a developer's work space and has no guarantees that
a given project will build right out of the box, or indeed, not dump core on
start up.

To clone all the history and branches of a project, from a shell:

{{{git clone http://git.gnome.org/[project] [project]}}}

You should replace {{{[project]}}} with the name of the project you
want. If you want the check-out to be put in a folder that is not the
same as the project name, specifiy your own folder name instead of the
second [project] instance.

Registered GNOME developers will be able to use their SSH key to
authenticate themselves to the Git server so that they make also push
changes back to the Git repositories. They will use a slightly
different URL to clone and deal with Git projects:

{{{git clone [login ]git gnome org/[project] [project]}}}

In this case, if your local login is not the same as your GNOME
developer login, you will also need to specify it in the URL.

When the clone has been completed, you will start to notice that
many projects in Git GNOME contain similar files:

 *.git: This directory is present in the root directory of a given
project. It contains information about version numbers, where the
source code came from, etc.. You can ignore it for all purposes, but
you should not delete it.
 * autogen.sh: This is a wrapper script around gettextize,
intltoolize, libtoolize, aclocal, autoheader, automake and autoconf
which you use to start building the project. For example
	{{{./autogen.sh --prefix=/usr/local}}}
	will start the build process checking your system, generating all the
necessary Makefiles before you are ready to type 'make' and 'make
install'.
 * ChangeLog: This is one of the most useful files for a developer to
keep up to date - it lists all the changes that a given  project has
undergone. In GNOME it is generally of the following form:
{{{
YYYY-MM-DD  Joe Bloggs <joe bloggs gnome org>

	* filename.c: Use gtk_dialog instead of deprecated gnome-dialog.
	Fixes #878372.
}}}

	If you are using Emacs, you can automatically generate a template
like this as you develop. There are also other scripts available to do
this.
	From eazel-hacking,
	[[http://developer.gnome.org/tools/scripts/prepare-ChangeLog.pl.txt|prepare-ChangeLog.pl]]
 * README: This generally gives information about the Git project in
terms of project requirements, where to report bugs etc..
 * HACKING: This file usually specifies the rules [if any] for
development in the project.
 * MAINTAINERS: This file lists the people who are responsible for the
day to day maintenance of the project. Generally these are the people
you should send patches to.

Git allows you to isolate changes onto a separate line of development, known
as a branch. Quite often in GNOME, there are stable and unstable branches of
development for a given project - as a result, the main branch [also known
as 'master'] may not be suitable for your needs. Stable branches in GNOME
Git are generally a mixture of lowercase alphabetic and numeric characters
separated by dashes ie. of the form:

{{{[project]-[MAJOR]-[MINOR]}}}

where major, minor are version numbers. For example:

{{{
gnome-2-0
gtk-2-0
}}}

In Git, branches and tags are simply references to a commit. You can
check out a branch using the following command, once you have cloned
the project:

{{{git checkout [branch name]}}}

For a list of the available branches for a given project:

{{{git branch -r}}}

The following example will check out gnome-utils master and then check
out the 'gnome-2-0' branch:

{{{
git clone http://git.gnome.org/gnome-utils
cd gnome-utils
git checkout gnome-2-0
}}}

Maintainers 'tag' their project to mark releases in GNOME Git. Tags in
GNOME Git are generally a mixture of uppercase alphabetic and numeric
characters
separated by underscores ie. of the form

{{{[PROJECT]_[MAJOR]_[MINOR]_[MICRO]}}}

where MAJOR, MINOR and MICRO are version numbers.  For example

{{{
GTK_2_0_6
GNOME_UTILS_2_0_2
}}}

For a list of the available tags for a given project:

{{{git tag -l}}}

Git was designed so that whenever there were any changes in the source
code, you didn't need to remove your sources and re-check out. The following
command syncs up your code with what is stored in the Git repository

{{{git pull}}}

When you pull, you will notice a summary of the changes transferred
(updated/new branches and tags) and a diffstat of the changes applied to your
working copy.

If you have conflicting changes in your working copy the changes will
not be applied.
You can stash them first, do the pull, and apply you changes again with:

{{{
git stash
git pull
git stash pop
}}}

If you still have conflicts, you must resolve these, in general, before being
able to rebuild the source code.

== Moving Forward ==

Now that you have successfully checked out a GNOME Git project and hopefully
managing to build it, you are ready to move forward and become a GNOME
contributor.

GNOME contributors send 'patches' [sometimes called 'diffs'] to each other and
attach them to bug reports in
[[http://bugzilla.gnome.org|bugzilla.gnome.org]]. A 'patch'
describes changes in some files. This generally gives you something of the
following form

{{{
<pre>
diff --git a/gcalc.c b/gcalc.c
index 9c0c81c..63c39a4 100644
--- a/gcalc.c
+++ b/gcalc.c
@@ -33,6 +33,7 @@
	gchar *authors[] = {
"George Lebl <jirka 5z com>",
"Bastien Nocera <hadess hadess net> (fixes)",
+               "Joe Bloggs <joe bloggs gnome org>",
NULL
	};
	gchar *documenters[] = {
</pre>
}}}

Here you can see the lines added prepended with a '+'. If you had removed [or
edited] a line of code, you would have been likely to see a line prepended
with '-'. Notice it also shows you the revision of the file you are
creating a patch against (in the index line).

Once you make changes to some given files you can generate a patch very easily
using the following command

{{{git diff [filenames] > [patch]}}}

This makes a patch of all the changes between your local changes and the
file that currently resides in the Git repository.
If you don't have any other changes you can omit the [filenames].

If you are the one that gets sent a 'patch', then you need to merge that
patch into your sources. For this you will need to use the following
command

{{{patch -p[n] < [patch]}}}

where n is the number of leading components to strip from the path. This
number is relative to where the patch was generated from - you can
experiment to get the correct number.
If you need to reverse a patch, you can use the following command

{{{patch -R < [patch]}}}

== Increased Trust ==

As you supply more and more patches to a given maintainer, or attach them
to bugs in bugzilla.gnome.org, the maintainer may ask you to obtain your
own Git account to make your own source code check ins.

To apply for your own Git account, please read the
[[http://live.gnome.org/NewAccounts|New Account]] instructions.

== Final Steps ==

With an increased amount of trust and responsibility, you may even be
asked to start maintaining a project within GNOME Git - or indeed, one
of your own that you may have
[[http://live.gnome.org/NewGITRepos|imported]].

One of the first things you will have to perform is to make releases on
a given project. The following steps are required, in most cases, to make
a release

 * Bump up the version number in configure.in file
 * 'autogen.sh' and 'make' the source
 * 'make distcheck' the source to obtain the release tarball
 * Commit the changes
 * Tag the release. To tag a given release, the following command is used:
  {{{
git tag -a [PROJECT]_[MAJOR]_[MINOR]_[MICRO] -m "Tagged for release x.y.z."
git push [remote] tag [PROJECT]_[MAJOR]_[MINOR]_[MICRO]}}}
  where MAJOR, MINOR and MICRO are version numbers and [remote] is the
name of the Gnome Git repository,
  normally 'origin'.
 * Write the NEWS for the project
 * Upload tarball onto ftp.gnome.org
 * Announce the release on
[[mailto:gnome-announce-list gnome org|gnome-announce-list gnome org]] 

At some point, you might find that it will be necessary to branch your
project for a stable set of releases, while continuing development on
master: Branching is very much like tagging, for example:

{{{
git branch [PROJECT]_[MAJOR]_[MINOR]
git push [remote] [PROJECT]_[MAJOR]_[MINOR]
}}}

where MAJOR, MINOR are version numbers and the branch is based on you
current branch.

Quite often you will need to apply some changes from the master to the
stable branch - generally for bug fixes that apply to both branches.

To apply a given patch to another branch, where you knew the revision
of the patch was 123:

{{{
git cherry-pick 123
}}}

Sometimes you will be required to reverse a given change made by
mistake. If the revision number of the patch that you wish to reverse
was 123, you could do this simply by the following command

{{{
git revert 123
}}}

== References ==

 * [[http://git-scm.com/|Git homepage]]
 * [[http://book.git-scm.com/|The Git Community Book]]
 * [[http://developer.gnome.org/tools/scripts/prepare-ChangeLog.pl.txt|Prepare
ChangeLog script]]
 * [[http://live.gnome.org/NewGITRepos|Importing projects into git.gnome.org]]