Guidelines for Packages Maintained on salsa.debian.org/java-team

This chapter adds additional guidelines for packages maintained in Salsa'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 under the java-team group on Salsa. Using the https://salsa.debian.org/java-team/pkg-java-scripts/blob/master/setup-salsa-repository script is RECOMMENDED for creating a new repository because it uses the correct options and sets up the notifications and hooks.

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?

Converting a Subversion repository to Git

Clone the repository containing the migration script at https://anonscm.debian.org/cgit/pkg-java/pkg-java-svn2git.git and then run:

./migrate-svn-repo-to-git <package>

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 dispatch+<package>@tracker.debian.org

Import upstream

You might have to create the upstream branch if you converted from svn: See the commands below Alternatively, if you are only importing source from original tarballs... in http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.import.html#GBP.IMPORT.CONVERT.

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

Note: Make sure you use the --filter-pristine-tar option if you use --filter options (otherwise your pristine-tar branch will be broken)!

This command

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:

Miscellaneous

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 note below.

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


CategoryJava CategoryPackageManagement CategoryGit