Status of this Page and Changes
NOTE: THIS INITIAL VERSION IS A DRAFT AND NEEDS DISCUSSION.
This page and the pages linked from here document best practices for using version control systems in the Java packaging team. It should make it easy to maintain a huge number of packages in an efficient way. But this is not a strict law. You MAY use your own rules if you document them in a central place: README.source. The words MAY, SHOULD, MUST, and others are used as in RFC 2119.
The Java packaging team uses Git on Salsa as the version control system (VCS). All team maintained packages SHOULD use one of this VCS. Packages that do not follow this rule MUST explain their VCS or state the fact of a missing VCS in README.source. Failing to document such deviations in README.source might lead to a bug report with severity serious. All packages MUST use appropriate Vcs-* headers in debian/control. Those headers SHOULD point to the VCS address that allows anonymous access (git: instead of git+ssh:).
Please read Java/JavaGit for Git guidelines. You SHOULD follow those guidelines. You MUST document any differences of your packaging workflow in README.source. Failing to document them in README.source might lead to a bug report with severity serious.
Default README.source Snippet
You SHOULD maintain a file README.source even if you follow all the rules. You can use the following snippet:
This package uses a version control system as described in http://wiki.debian.org/Java/JavaVcs and the pages linked from there.
You might need to add more information according to Debian policy Source package handling: `debian/README.source'
Source Format and Patch System
You SHOULD use source source format 3.0 (quilt) if you need to patch the upstream code. Other patch systems like dpatch, cdbs, or plain quilt SHOULD NOT be used. Using the source format 3.0 (quilt) without any patches is OPTIONAL but it makes it easier to add patches in the future. The patches SHOULD follow the Patch Tagging Guidelines as described in DEP-3 which is almost trivial with the gbp-pq tool.
Original Tarball and Upstream Version
Adding a dfsg suffix to every upstream version is OPTIONAL because most of the packages are affected. Creating the original tarball from an upstream Vcs tag is preferred over cleaning up and repacking an upstream archive file in most cases. Packages SHOULD ship debian/watch if possible.
Debian/watch MAY call helper tools (like debian/orig-tar.sh) if needed to clean up the original file or to create a tarball from a Vcs tag (using the Files-Excluded fields in debian/copyright is preferred). These requirements are OPTIONAL if both Debian and upstream are using Git and the upstream tarball can be easily created with pristine-tar.
Using pristine-tar is RECOMMENDED for all git maintained packages.