Software/ooo-build/GettingIt

Contents

  1. Getting the sources
  2. Basic instructions
  3. Getting a particular branch
  4. Getting a particular tag
  5. Getting the latest updates
  6. Committing the changes
  7. Pushing the changes
  8. What if I committed something wrong
  9. Introducing a change in more branches
  10. Mailing the changes
  11. Tagging a release
  12. Creating a release branch
  13. Managing translations (info for translators)
  14. More info

Getting the sources

ooo-build sources are stored in git. To clone the latest version of ooo-build, please use: 

git clone git://anongit.freedesktop.org/git/ooo-build/ooo-build

Registered developers should use the following command to enable writing to the repository: 

git clone ssh://[username@]git.freedesktop.org/git/ooo-build/ooo-build

If you asked for your account, but did not get one yet, just clone from the anonymous repository, you can commit and pull -r immediately, and push the changes later when you have the read/write access. You can also send the changes by mail if you need them in the repository on freedesktop.org earlier.

To change your anonymous clone into a read/write one, change the URL in .git/config from the anonymous one to the read/write.

Basic instructions

Please check our SVN to git cheat sheet for quick reference.

Getting a particular branch

When you have cloned the repository, you can switch to any branch you need. The bleeding edge development happens in master, which is what you get when you clone the repository. To switch eg. to branch ooo-build-3-0-1, do: 

git checkout -b ooo-build-3-0-1 origin/ooo-build-3-0-1

This exactly means "please create a local branch ooo-build-3-0-1 that tracks what's happening in the remote branch ooo-build-3-0-1". You can get a list of all the available remote branches using git branch -r.

Once you have created the branch(es), you can switch between them using git checkout: 

git checkout master
git checkout ooo-build-3-0-1

Note: You might want to keep the older ooo-build branches in separate locations. When you have cloned ooo-build master to eg. ~/ooo-build, you can use the --reference feature of git clone to save bandwidth: 

git clone --reference ~/ooo-build \
    ssh://[username@]git.freedesktop.org/git/ooo-build/ooo-build ooo-build-3-0-1
cd ooo-build-3-0-1
git checkout -b ooo-build-3-0-1 origin/ooo-build-3-0-1

We recommend you to have the branch you are interested in as the only branch there: 

# remove the master branch in this repository, we are interested only in ooo-build-3-0-1
git branch -D master

Getting a particular tag

To switch your local repository to the given tag, use the following command: 

# let's say we want the tag OOO_BUILD_3_0_99_3
git checkout -b tag-OOO_BUILD_3_0_99_3 OOO_BUILD_3_0_99_3

This exactly means "please create a local branch tag-OOO_BUILD_3_0_99_3 that shows the state of the sources when the tag OOO_BUILD_3_0_99_3 was created". For the operations like diff, log, etc. you don't have to create the branch; just directly do 

git log OOO_BUILD_3_0_99_3
git diff OOO_BUILD_3_0_99_3 master

The tags are created for released sources, branches or some specific commits. To list them all, use: 

# ensure that you have all the tags from the remote repository
git pull -t
# show the tags
git tag

Getting the latest updates

We use the same git workflow as described in the common freedesktop.org git instructions. The reasoning is simple - using just the git pull (without the -r) tends to create too many unnecessary 'merge' commits when there are more people working on one repository - and this is what we want to avoid.

So, to get the updates, use 

git pull -r

Please, do not forget the -r ! - -r means that instead of merging, git pull rebases your local changes against the changes from the remote repository. See also the Pushing the changes section.

Committing the changes

When you commit your changes, it happens locally; you have to push your commits later so that they appear in the remote repository.

You probably want to use any of the following forms of committing 

# commit all the changed or removed files
git commit -a
# commit the specified files
git commit file1 file2 file3 ... fileN
# first mark the files that you want to commit, then commit them
git add file1 file2 file3 ... fileN
git commit

Of course, there's also the usual: 

git rm file1 file2 # remove file
git mv source dest # move file
git commit         # commit the removes/moves

Note that there is no git cp - git detects the history for file moves/copies after the fact, so you should be OK with only using 

cp file1 file2
git add file2
git commit

The commit logs should have the following form: 

First line roughly describing the change.

Leave one empty line, and then follow with more detailed description
what and why you changed.  It is really important to provide a good
description on the first line, because some of the git tools (like
gitk, git log --pretty=oneline, git rebase --interactive, etc.) show
just the first line.  Also we don't have a ChangeLog any more, so
git log is now your source of the information about the changes.

Please do not forget to mention the bugzilla numbers, like i#12345 or
bnc#234567.

* file1: Did this and that.
* file2: And something else here.

You can leave out the '* file: Did this and that' part if the general description is descriptive enough, or leave out the general description, if you store all the info in '* file: XYZ' part, but please never ever forget to provide a good first line.

The commit hooks that get installed when you do ./autogen.sh should help you to create good commit messages.

Pushing the changes

If you have write permissions to the remote repository, and want to publish your changes, push them to the repository using 

git push

When it fails because somebody else has pushed something, update your repository using 

git pull -r

as already described above. Again, don't forget the -r!

Note: If you used just 'git pull' instead of 'git pull -r' accidentally, you can still fix that by re-running git pull -r. There is also a hook that warns about the plain 'git pull' usage, and instructs you what to do.

Note2: You might get warnings during git push when you have multiple branches to push in your repository (which happens when you eg. did not delete the master branch though it is recommended in 'Getting a particular branch'). These are just warnings, but if do not want to get them, use the full form of git push: 

# let's push just the branch 'ooo-build-3-0-1'
git push origin ooo-build-3-0-1

What if I committed something wrong

If you did not push it yet, all is fine. Just use 

git rebase -i origin/master
# [this supposes you are in the 'master' branch; for ooo-build-3-0-1
# you would use origin/ooo-build-3-0-1]

and edit the history. The use of origin/master as the starting commit decreases the probability that you'll do something wrong.

'git rebase -i' presents you with a list of the commits and a small help; you can let the commit as it is, move it up/down, remove it, squash it together with the previous commit(s), or edit it.

After you save the list, each time there is a conflict, or when rebase finds a commit to edit, you get a shell, do your changes, git add the.txt changed.txt files.txt, and git rebase --continue. After few iterations, and with a bit of luck, all will be as good as you wanted.

However - if you pushed your changes already, don't you try to rebase them! You have to commit the fixes and push them as completely new stuff.

Introducing a change in more branches

To get commits from other branches, please use 

git cherry-pick <commit-id>

It will take the changes introduced in <commit-id>, and commit them in the current branch.

We may allow full merges from other branches in the future, but so far we do not consider it safe on the branches automatically converted from the SVN.

Mailing the changes

If you do not have the write permissions [yet ;-)], just develop like if you had one & commit the stuff to your local repository. Then instead of 'git push' please mail the results of 

# if you are on the branch 'master', and want to mail the commits done there
git format-patch origin/master
# more verbose version, when you want to eg. mail changes committed on branch ooo-build-3-1
git format-patch origin/ooo-build-3-1..ooo-build-3-1

to the dev@lists.go-oo.org mailing list. One of the developers with the write access will review, and push them for you using 

# apply the patches from the mailing list
git am 0001-the-first.patch 0002-the-second.patch 0003-the-third.patch
# check them briefly
git log
# check them better
git log -p
# push
git push

Tagging a release

When you want to tag a release, you have to first create the tag, and then push it: 

# create a tag, signed by the GPG key you configured using git config user.signingkey
git tag -s <tag-name>
# push the tags to the remote repository
git push --tags

You can also create the tag using another key (git tag -u <key-id> <tag-name>), or create an unsigned tag (git tag -a <tag-name>); though you should avoid the unsigned tags.

Creating a release branch

When there's a particularly good reason for a branch, such as a MWS is moved to the maintenance mode and we want open master for further development, one of the core ooo-build hackers will follow something like this: 

# the branch is usually created from a beta release tag
# checkout the tag OOO_BUILD_I_J_K into the new branch ooo-build-X-Y-Z
git checkout -b ooo-build-X-Y-Z OOO_BUILD_I_J_K
# alternatively, you might do the branch from the current master
#   git checkout -b ooo-build-X-Y-Z master
# create the tag in that branch and use the comment
git tag -s OOO-BUILD-X-Y-Z-ANCHOR
>    Tag OOO-BUILD-X-Y-Z-ANCHOR for the branch ooo-build-X-Y-Z
# modify the message printed at the end of 'configure.in'
vim configure.in
>    This is ooo-build-2-0-4 - the stable branch for the 2.0.4 release.
>    If you want to build something cool, unstable, and risky, use master.
# commit the changes and use the comment:
git commit -a
>    Branch ooo-build-X-Y-Z (stable branch for OOo-X.Y.Z)
>    
>    Branch     ooo-build-X-Y-Z
>    Anchor tag OOO-BUILD-X-Y-Z-ANCHOR
>    
>    based on ooo-build, version I.J.K, tag OOO_BUILD_I_J_K
# push the branch
git push origin ooo-build-X-Y-Z:ooo-build-X-Y-Z
# push the tag
git push --tags

And there might be some changes needed in the original tree (master) too. 

# switch back to the master
git checkout master
# if it is an important branch, such as for a minor OOo version, add
# a line to the message printed at the end of 'configure.in'
vim configure.in
>    ooo-build-X-Y-Z  branch for X.Y.Z
# commit the changes
git commit -a
# push the changes
git push

Managing translations (info for translators)

ooo-build includes two different .po files:

Translators need not take care of .pot or .sdf files. They are regenerated by ooo-build developers when necessary (before release). Any new or updated .po file can be either pushed directly to ooo-build (in case you have the fd.o account) or mailed to the mailing list. See Mailing the changes section on how to do it.

See also ooo-build/po/README.

More info