• GlibcGit

GLIBC moved to the git SCM in May/June 2009.

Static GLIBC releases from the CVS days are still available in the git repository under the cvs/ name space as branches.

Current upstream maintenance all takes place in git under the master/ name space.

Fetching The Repository

You can use git to check out the sources, including all revision history, with this command:

git clone git://sources.redhat.com/git/glibc.git

That command downloads about 88MB of data which goes into the glibc/.git/ repository, and checks out the source tree, which occupies an additional ~170MB.

Similarly, for the glibc ports add-on, you can:

git clone git://sources.redhat.com/git/glibc-ports.git

To view the recent check-ins do:

git log

To revert the tree to a specific commit do:

git checkout <revision gleaned from git log>

e.g.

git checkout d849666474d7cc33521b1c54b489901289de9e63

• The repository is mirrored at http://repo.or.cz/w/glibc.git with some extra gitweb features and especially allowing developers to easily publish repositories with their glibc changes at the site.

For information on checking-out and working with branches skip ahead to Working With Branches.

Branch Name Space Conventions

Conventions for GLIBC git name space branches come in two tiers.

1. Top-tier name space branch conventions for the whole repository are owned and administered by the GLIBC maintainers and cover the copyright requirements and assignment of unique name_space/* branches to an individual owner.

   • The community at-large may make suggestions for top-tier convention proposals.

2. Second-tier branch conventions are described per name space and are defined by the name space owner and detailed in a unique wiki page linked to via a cell in the name space table's 'Details on Second-Tier Conventions' column.

The currently approved Top-Tier name space branch conventions are:

Requesting a Name Space

The generic policy for requesting a Top-Tier name_space/* branch in the GLIBC git repository is as follows:

• Note: This policy was defined by Roland McGrath on the libc-alpha mailing list in this thread.

1. Propose a name for the name_space/* branch, owner, intended commit policy, and intended commiter(s) on the libc-alpha mailing list (if nobody calls you rude names, then consider it approved).

   • The proposed owner(s) and commiter(s) must have existing FSF copyright assignment on file with the FSF.
   • The community might have some suggestions on the top-tier policies but it's your playpen.

2. Update the name space table to reflect the new name_space/* and owner/commiter(s) (use their sourceware.org username).

   • To request a sourceware.org username use the following handy dandy little form.

   • While each owner is free to set branch policies and commit approval in their name space as they like; all people authorized to push (i.e. commit) will need sourceware accounts authorized for the glibc group.

3. Email overseers@sourceware.org (and CC Roland McGrath roland@redhat.com) and request that the proposed commiters be added to the glibc group.

   • See this email template for information that should be relayed to the sourceware.org overseers.

   • Adding each person to the group goes through the normal overseers process with explicit approval from Roland or another GLIBC maintainer required.
   • The GLIBC maintainers and the Overseers will expect a vouching for sanity and competence, that the person both really, truly understands FSF copyright protocols, and always carefully respects per-branch policies on what they are allowed to touch and how.

4. Create a unique wiki page as a child of the GlibcGit/ page (e.g. GlibcGit/ibm_namespace) describing the second-tier policies, mission, and branches for the name space.

5. Update the table cell that is the intersection of the Details on Second-Tier Conventions column and the proposed name space/* row of the name space table to show the intra-wiki link to the newly created unique wiki page for the name space.

A previous request to follow as an example can be found for the ibm/* name space in the following libc-alpha mailing list email http://sources.redhat.com/ml/libc-alpha/2009-06/msg00166.html.

Release Management

1. Don't talk about recommended guidelines for all release branch managers. No, wait, do talk about them. Don't suspect your neighbor. Discuss him on libc-alpha.

2. Remember GNU copyright discipline, even for private branches.

3. Use git branch "release/x.y/master" as "the usual place to look" (whatever that means in your process). The x.y release manager should choose and specify conventions for "release/x.y/*" branches.

4. When a commit backports a change from the trunk (or another proper release branch), use "git cherry-pick -x" or otherwise clearly indicate the original commit id in the backport commit's log entry, and always aim for one separate backport commit per corresponding trunk commit.

5. When a commit is not a backport of a clearly identifiable single commit from the trunk or another release branch, then there should be some voluminous controversy or communal agonized consternation on the mailing lists about whatever it is. i.e., this should always be an automatic red flag for a release manager and all participants, so that it merits explicit discussion more than the usual routine.

6. Try to pay attention to what your past (or concurrent) predecessor release managers have done, and learn from their examples and mistakes.

7. Do not taunt Happy Fun Drepper.

8. The release manager has veto.

Git Help For Committers

The following sections should only be necessary for approved git commiters.

Commit Messages

The git commit messages should be descriptive and not just repeat the ChangeLog entry.

The ChangeLog entry should be written as before.

The git commit message can be a single line or a more extensive text, depending on the problem.

To help git tools, multi-line commit messages should have the second line empty.

The BZ number should be in the commit message, too, but not as the sole content of the first line (as the automatic converter arranged it).

Setting Username

If your sourceware.org username differs from your local system login username you can set the global git username as follows:

git config --global user.name "sourceware.org username"
git config --global user.email "username@host"

This can be overridden on a per-repo basis. First, check out the tree:

Grab the tree:

git clone git://sources.redhat.com/git/glibc.git

Then cd into the tree and set the user.name and user.email locally:

cd glibc
git config user.name "sourceware.org username"
git config user.email "username@host"

Creating A New Top-Tier Name Space

Once you have approval to create a Top-Tier name_space/* branch you'll need to think about some Second-Tier name space branches and related Second-Tier topic branches.

• While you don't need Second-Tier topic branches like 'master' it is probably useful as a common topic branch for Second-Tier policies.

• Otherwise your Second-Tier name space is the branch you check out.

In general you probably want a Second-Tier 'master' topic branch which is branched from an official release branch.

Any further Second-Tier topic branches should probably branch from that Second-Tier 'master' topic branch, e.g.:

Grab the tree:

git clone git://sources.redhat.com/git/glibc.git

Create the Second-Tier master topic branches in the name_space/* name space:

cd glibc
git branch name_space/2.8/master origin/cvs/glibc-2_8-branch
git branch name_space/2.10/master origin/release/2.10/master
git branch name_space/master master

Create additional Second-Tier topic branches based on the newly created name_space/2.10/master branch:

git branch name_space/2.10/foo name_space/2.10/master

Misnamed a branch?

git branch name_space/2.10/bar name_space/2.10/master

Simply delete it from your local repository and fix it before you git push, but be careful, -D is unforgiving.

git branch -D name_space/2.10/bar
git branch name_space/2.10/foo name_space/2.10/master

Before you git push you should examine the branch structure you've created and you'll see something like this:

  name_space/2.10/foo
  name_space/2.10/master
  name_space/2.8/master
  name_space/master
* master
  origin/HEAD
  ... et al ...

If you need to make some changes in a branch before you commit it you need to switch to the local branch, i.e. sans origin/ in the path since it hasn't been pushed upstream yet:

git checkout name_space/2.10/master

Git push the name_space/* name space branches upstream to add the name_space/* name space branches to the official GLIBC git repo:

git push git://sources.redhat.com/git/glibc.git name_space/2.8/master:name_space/2.8/master
git push git://sources.redhat.com/git/glibc.git name_space/2.10/master:name_space/2.10/master
git push git://sources.redhat.com/git/glibc.git name_space/2.10/foo:name_space/2.10/foo
git push git://sources.redhat.com/git/glibc.git name_space/master:name_space/master

Update your local repository to reflect the git push:

git remote update

Examine the structure and you should see something like this:

* master
  origin/name_space/2.10/foo
  origin/name_space/2.10/master
  origin/name_space/2.8/master
  origin/name_space/master
  origin/HEAD
  ... et al ...

Working With Branches

You can switch to a specific branch that the official GLIBC git repository provides. First, check out the tree:

git clone git://sources.redhat.com/git/glibc.git

To view current branch availability use git branch:

cd glibc
git branch -a

You will see something like the following:

* master
  origin/ibm/2.10/master
  origin/ibm/2.8/master
  origin/ibm/master
  origin/HEAD
  origin/cvs/fedora-2_3-branch
  origin/cvs/fedora-2_5-branch
  origin/cvs/fedora-branch
  origin/cvs/glibc-2-1-branch
  origin/cvs/glibc-2-2-branch
  origin/cvs/glibc-2_0_x
  origin/cvs/glibc-2_10-branch
  origin/cvs/glibc-2_3-branch
  origin/cvs/glibc-2_5-branch
  origin/cvs/glibc-2_6-branch
  origin/cvs/glibc-2_7-branch
  origin/cvs/glibc-2_8-branch
  origin/cvs/glibc-2_9-branch
  origin/cvs/master
  origin/cvs/sparc-2_0_x-branch
  origin/cvs/thomas-posix1996
  origin/fedora/2.10/master
  origin/fedora/master
  origin/master
  origin/release/2.10/master

When switching to a branch to do development there are two options:

1. Create a new branch that is branched from the origin branch.
   • Recommended method.

2. Work directly in the origin/name_space/ branch.

   • This is discouraged since you now have no easy way to diff against the original release branch code since you polluted it.

Working From a New Branch

Create the new branch based on a specific branch and switch to it:

git clone git://sources.redhat.com/git/glibc.git
cd glibc
git checkout -b foo_2.10 origin/release/2.10/master

You can verify that you've switched to this branch with:

git branch -a | grep "foo"

Which should show:

* foo_2.10

To push the changes in this local branch upstream you need to tell git which branch it's intended to update:

• Note: this particular example pushes to the release/ Top-Tier name space which only Release maintainers are allowed to modify. Take care!

git push git://sources.redhat.com/git/glibc.git foo_2.10:origin/release/2.10/master

Working Directly in The Origin Branch

Switch to the desired branch:

git clone git://sources.redhat.com/git/glibc.git
cd glibc
git checkout origin/release/2.10/master

Perform your changes and then push them upstream:

• Note: this particular example pushes to the release/ Top-Tier name space which only Release maintainers are allowed to modify. Take care!

git push git://sources.redhat.com/git/glibc.git origin/release/2.10/master:origin/release/2.10/master

Merging Changes From A Tracked Branch

If you are a Top-Tier name space owner or commiter you may need to update your name space branches with the latest version of code from the branches from which they were originally branched.

As an example, let's say:

• name_space/2.10/master generally tracks release/2.10/master

• name_space/2.10/master contains everything in release/2.10/master plus additional changes unique to name_space/*.

• release/2.10/master is updated with new patches.

• name_space/2.10/master will want to merge those changes so they need to be merged into the name_space/2.10/master branch.

Assume you've checked out to the name_space/2.10/master topic branch:

git clone git://sources.redhat.com/git/glibc.git
cd glibc
git checkout -b local_2.10 origin/name_space/2.10/master

If there are no local changes just merge from the release/2.10/master branch:

git remote update
git merge origin/release/2.10/master
git push git://sources.redhat.com/git/glibc.git local_2.10:name_space/2.10/master

If there are local changes git rebase will need to be used.