Differences between revisions 15 and 16
Revision 15 as of 2012-11-27 18:51:59
Size: 6867
Editor: ?Felix Natter
Comment:
Revision 16 as of 2012-11-28 20:31:38
Size: 6892
Editor: ?Felix Natter
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

<<TableOfContents()>>

Guidelines for Packages Maintained on git.debian.org:/git/pkg-java

This chapter adds additional guidelines for packages maintained in Alioth's git repositories. Please read the page Java/JavaVcs first if you have not done yet. Most of the guidelines are inspired by git-buildpackage.

Git repositories can be created in the directory /git/pkg-java or in a subdirectory at git.debian.org. The WWW interface is available at http://anonscm.debian.org/gitweb/. Using the /git/pkg-java/setup-repository script is RECOMMENDED for creating a new repository because it uses the correct options and sets up the mailing lists.

Contrary to subversion the upstream code SHOULD be imported. Every new upstream version SHOULD be tagged as upstream/VERSION after cleaning it up. Using pristine-tar is RECOMMENDED. The pristine-tar branch SHOULD be called pristine-tar. Having an explicit upstream branch is OPTIONAL but it SHOULD be called upstream if it exists.

Every repository should have a master branch with the upstream code, the Debian code and patches. The newest version of README.source MUST be available in the master branch. The patches SHOULD be unapplied before committing changes.

You MAY push upstream tags to Alioth if upstream uses git. But you SHOULD always create an explicit tag upstream/VERSION even if it is identical to some upstream tag. You MAY skip adding a get-orig-source target in debian/rules if you create the upstream/VERSION tag directly in git without any intermediate tarball. You MUST document the workflow for upstream updates in README.source in such cases. The tarball used in the successful upload SHOULD be committed with pristine-tar.

Every successful upload MUST be tagged as debian/VERSION.

Branches and tag schemas not mentioned here MUST be documented in README.source. Any required tools except git-buildpackage and pristine-tar MUST be documented in README.source.

QUESTION: do we need guidelines about .gitignore, .gitattributes, and .gbp.conf?

Using Git

We use git together with mr (Multiple Repository management tool) to track the git repositories for each package.

Obtaining the master repository

git clone <alioth-username>@git.debian.org:/git/pkg-java/pkg-java.git

NOTE that your public key must be known to alioth in order for this to work, see here.

Then, to obtain all the team packages, do:

cd pkg-java
# look at .mrconfig
apt-get install mr
mr checkout

To enable parallel checkouts, use

mr -j 5 checkout

To avoid typing your username and your password see this page.

WARNING: as of December 2011, the pkg-java repository uses 5.5 GB of space.

To get the latest sources from all packages, do

mr -j 5 update

Converting an SVN repository to Git

You'll need an authors file to have pretty full names and email adresses in the Git log. You can start with this list. Please add more pkg-java authors.

drazzib = Damien Raude-Morvan <drazzib@debian.org>
gg0-guest = gg0 <gg0@unknown.com>
ludovicc-guest = Ludovic Claude <ludovic.claude@laposte.net>
mkoch = Michael Koch <konqueror@gmx.de>
twerner = Torsten Werner <twerner@debian.org>
tmancill = Tony Mancill <tmancill@debian.org>
fourmond = Vincent Fourmond <fourmond@debian.org>
pcc-guest = Peter Collingbourne <peter@pcc.me.uk>

(Somebody with SVN installed might run this line to find more authors

svn log "svn://svn.debian.org/svn/pkg-java/" | awk -F'|' '/^r[0-9]+/ { print $2 }' | sort -u >/tmp/pkg-java-authors

You can then convert a pkg-java SVN repo with something like:

git svn clone  --authors-file=/tmp/pkg-java-authors --no-metadata \
    --trunk=trunk/maven-repo-helper \
    --tags=tags/maven-repo-helper \
    svn+ssh://thkoch-guest@svn.debian.org/svn/pkg-java/

You must give your own Alioth username and replace "maven-repo-helper".

Using git-buildpackage

This chapter gives some instruction about using git-buildpackage. The full manual can be found at https://honk.sigxcpu.org/piki/projects/git-buildpackage/.

Create the git repository on git.debian.org

<login>@vasks:~$ cd /git/pkg-java
<login>@vasks:/git/pkg-java$ ./setup-repository <package>
Initialized empty shared Git repository in /srv/git.debian.org/git/pkg-java/<package>.git/
Repo <package>.git has been created
Commit messages for <package>.git have been forwarded to pkg-java-commits@lists.alioth.debian.org and <package>_cvs@packages.qa.debian.org

Import upstream

git-import-orig --filter "*.jar" --filter "*.war" \
                --filter apache-solr-1.4.0/docs/api \
                --filter apache-solr-1.4.0/dist --filter-pristine-tar \
                --pristine-tar -u1.4.0 ../apache-solr-1.4.0.tgz

This command

  • filters out (repackages) unwanted files from the upstream tarball,
  • imports the (filtered) upstream tarball into the git branch "upstream",
  • tags the import with the version number,
  • merges the updated upstream into the packaging branch "master"
  • and creates a pristine-tar import to restore the (filtered) upstream tarball.

The --filter options are translated directly to tar --exclude options. See man tar for details.

--filter-pristine-tar makes sure that the same filtering is also applied to the pristine tarball. Therefor the tarball saved with prisitine-tar isn't pristine anymore, but rather repackaged.

So the shellscript debian/orig-tar.sh from the solr package which manually removes all *.jar and repackages the upstream tarball isn't necessary anymore.

You may want to make two imports with git-import-orig for each new upstream tarball. The first import is without any filtering and saves the original tarball as it for later reference. The second import adds a "+dfsg" suffix to the tarball, filters all jar files and is the one actually uploaded to debian.

You may need to manually remove .git directories from the orig.tar.gz

Typical git workflow

git workflow is quite straightforward:

  • fetch tarball
  • git-import-orig <tarball> (updates upstream and pristine-tar branches)

  • update changelog and other files
  • do package improvements, remove patches applied upstream, etc.
  • debcommit -a (does a local commit in the master branch)
  • git-buildpackage (which uses cowbuilder in my setup)
  • local testing
  • dch -r
  • git commit -a -m "Release ...."
  • git-buildpackage --git-tag --git-sign-tags (produces and tags the release for upload)
  • dput <...>.changes

  • git push --all (pushes all local changes to the repo at git.d.o)
  • git push --tags (pushes the tags)


CategoryJava CategoryPackageManagement CategoryGit