xorg: Changes to 'xsf-docs'
xsf-docs/reference/git-usage.txt | 190 +++++++++++++++++++++++++++++++++++++++
1 file changed, 190 insertions(+)
New commits:
commit 15ac25a426af414f2cc3fdec1da8aa49d23c06b7
Author: Cyril Brulebois <kibi@debian.org>
Date: Thu Jun 2 21:16:05 2011 +0200
reference/git-usage: New doc.
diff --git a/xsf-docs/reference/git-usage.txt b/xsf-docs/reference/git-usage.txt
new file mode 100644
index 0000000..cdf89dd
--- /dev/null
+++ b/xsf-docs/reference/git-usage.txt
@@ -0,0 +1,190 @@
+Git usage
+=========
+:toc:
+Cyril Brulebois <kibi@debian.org>
+
+
+[NOTE]
+The old documentation is still available on the wiki:
+http://wiki.debian.org/XStrikeForce/git-usage[wiki.debian.org/XSF/git-usage];
+this documentation is just a draft for now.
+
+
+Foreword
+--------
+
+Upstream repositories are hosted on
+http://cgit.freedesktop.org/[git.freedesktop.org]
+
+Debian repositories are hosted on
+http://git.debian.org/[git.debian.org] under the `pkg-xorg/*`
+namespace. Each repository is about a single Debian source package.
+
+We have two types of repositories:
+
+* *regular* packages: 1 upstream repository → 1 Debian repository → 1
+ Debian source package (non-native).
+* *bundle* packages: multiple upstream repositories → 1 Debian
+ repository → 1 Debian source package (native).
+
+A local git repository can have several remotes. In the context of
+Debian packaging, one usually starts by cloning the Debian repository,
+so `origin` will likely point to `git.debian.org`. One can use
+`upstream` to point to `anongit.freedesktop.org`. The following
+documentation assumes this convention.
+
+To get the repository from `git.debian.org` one can run `debcheckout
+$package` (or `debcheckout $package $package.git`), which will use the
+`Vcs-Git` fields in the APT cache to pick the appropriate git
+location. To add the `upstream` remote (using the info stored in
+`debian/watch`), one can use `xsf-remote-add-upstream` script from the
+http://git.debian.org/?p=pkg-xorg/debian/xsf-tools.git[pkg-xorg/debian/xsf-tools.git]
+repository.
+
+**TODO:** There will be more information about how to deal with the
+many repositories maintained by the X Strike Force in a later chapter.
+
+The usual workflow is to keep the target suite in `debian/changelog`
+to `UNRELEASED` until the upload happens, the last commit before a
+commit being only `dch -r`. To achieve that, and to avoid noise since
+those packages are comaintained, it’s advised to set the following
+variable in `~/.devscripts`:
+
+----
+DEBCHANGE_RELEASE_HEURISTIC=changelog
+----
+
+
+Regular packages
+----------------
+
+For most packages (exceptions include `xorg-server`), development is
+linear, and happens in a `master` branch. That `master` branch is
+pushed in the Debian repository as `upstream-$suite`
+(e.g. `upstream-unstable`), depending on the target suite. Usually,
+`upstream-unstable` tracks `upstream/master`.
+
+The packaging is kept in `debian-$suite` branches, branched from
+`upstream-$suite`. When cloning a Debian repository, the default
+branch is `debian-unstable`.
+
+To create the initial packaging from the `upstream-unstable` branch,
+just run `git checkout -b debian-unstable`, add packaging files
+(`changelog`, `control`, `copyright`, `rules` etc. under `debian/`),
+and that’s it.
+
+Here’s how to merge from upstream (`$foo` being a tag or
+`upstream/master`):
+
+----
+ git checkout upstream-unstable
+ git merge $foo
+ git log $foo > ChangeLog
+ dch -v $debianrevision
+ git commit -am 'Bump changelogs.'
+----
+
+`$debianrevision` is usually `$foo` with `-1` appended (first upload),
+and sometimes prepended with a epoch (for example `2:`). Passing
+`$foo-1` is usually a good rule of thumb, since `dch` will complain if
+the epoch is missing (given the specified version string wouldn’t be
+newer than the current one).
+
+When development isn’t linear
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For packages like `xorg-server` and `libx11`, there are stable
+branches which receive updates for a while. Trying to switch from
+`1.10.2` to `1.11.0` might trigger a lot of conflicts. But in the end
+what matters is the changes between `upstream-$suite` and
+`debian-$suite`. Here’s an example, supposing `upstream-unstable` and
+`debian-unstable` are pointing to the “old” branches, and supposing
+the new branch is `upstream/master`:
+
+----
+git checkout -b debian-unstable-new upstream/master
+git merge -s ours upstream-unstable
+git merge debian-unstable
+git branch -d debian-unstable
+git branch -m debian-unstable
+----
+
+Subtitles:
+
+* Create a `debian-unstable-new` branch starting with the upstream
+ `master` branch, and switch to it.
+* “Merge” the old `upstream-unstable` branch, actually keeping only
+ the new upstream branch.
+* Merge the old packaging on top of it.
+* Remove the old branch (so that the name can be reused).
+* Rename the current `debian-unstable-new` branch into
+ `debian-unstable`.
+
+Since the tip of the new `debian-unstable` branch is a descendant of
+the tip of the old `debian-unstable` one, it can be pushed normally.
+
+Since old `upstream-unstable` and new `upstream-unstable` diverged,
+this branch has to be pushed with a `-f` to force the update (it’s not
+a fast-forward).
+
+
+Bundle packages
+---------------
+
+One bundle package is a Debian native package, with just a (Debian)
+tarball, instead of an upstream tarball plus a Debian diff.
+
+There is no upstream branches here, only `debian-$suite`.
+
+The repository contains a `debian/` directory for the packaging, and
+one directory per upstream source. Merging a new upstream release
+means updating the contents of the relevant directory with the
+contents of the new upstream tarball. Fetching new tarballs is
+automated through a specific target: `make -f debian/rules
+get-tarballs`
+
+To perform an update, first run `dch -i` to create a new changelog
+entry if the previous commit was an upload (the new entry targets the
+`UNRELEASED` suite, see “Foreword”).
+
+Assuming `get-tarballs` made `foo-bar.tar.gz` appear in the top-level
+directory, here’s how to update (trailing slashes are not needed, just
+there to clarify we’re working on directories):
+
+----
+git rm -r foo/
+tar xf foo-bar.tar.gz
+mv foo-bar/ foo/
+git add foo/
+dch "foo bar"
+debcommit -a
+----
+
+Using the `xsf-remote-add-upstream` script will create several
+`upstream-$foo` remotes, using info stored in `debian/watch*`. This
+helps browsing the history of a given repository (rather than having
+to look at a big fat diff with autogenerated files in the middle).
+
+
+Upgrade checklist
+-----------------
+
+[NOTE]
+Since it’s likely for a reader of this page to be on her way to update
+a package, here’s a tiny upgrade checklist.
+
+Basic checks include looking into what happened to those files since
+the last packaging update:
+
+* `COPYING`: Update `debian/copyright` accordingly.
+* `configure.ac` (or `configure.in`): Update (build-)dependencies
+ accordingly.
+
+About xorg macros (they show up very often in the diff), they’re
+shipped in the `xutils-dev` package, which contains a file to help map
+macro versions and package versions:
+`/usr/share/doc/xutils-dev/versions`
+
+Some packages might have more specific instructions. That’s the case
+for at least `xorg-server`. See its `debian/README.source`, below the
+generic “how to use quilt” blurb.
Reply to: