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:
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 firstname.lastname@example.org and dispatch+<package>@tracker.debian.org
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)!
- 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)
- git push --all (pushes all local changes to the repo at git.d.o)
- git push --tags (pushes the tags)
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