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.
Subversion and Git
The Java packaging team uses either subversion or git as a version control system (VCS) on Alioth. All team maintained packages SHOULD use one of those 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 (svn: or git: instead of svn+ssh: or git+ssh:).
You MAY freely choose between subversion or git if you are starting a new package. Pick the VCS that you are more familiar with.
You MAY move an existing package from subversion to git if there is a good reason. Maybe all active maintainers agreed on moving to git. Maybe upstream uses git and you want to merge and cherry-pick from the upstream repository. You SHOULD leave a file README in the subversion repository that mentions the new VCS address. NOTE: WE NEED SOME EXPLANATION / TOOLS FOR THE TRANSITION.
You SHOULD NOT move package from git to subversion because we would certainly lose the history.
Please read Java/JavaSvn for subversion guidelines and 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 policy 4.14. 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.
Packages SHOULD implement a get-orig-source target in debian/rules if possible. That MAY be implemented by calling uscan with the appropriate command line arguments. Debian/watch SHOULD 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. 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.