Differences between revisions 14 and 15
Revision 14 as of 2018-05-04 15:42:53
Size: 3150
Editor: ?EmmanuelBourg
Comment: Recommend using Files-Excluded instead of debian/orig-tar.sh
Revision 15 as of 2018-05-31 11:01:45
Size: 3175
Editor: ?EmmanuelBourg
Comment:
Deletions are marked like this. Additions are marked like this.
Line 11: Line 11:
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:}}}). The Java packaging team uses Git on Salsa as the version control system (VCS). All team maintained packages SHOULD use 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:}}}).
Line 32: Line 32:
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. The {{{debian/watch}}} file 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}}} field 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.

Status of this Page and Changes

NOTE: THIS INITIAL VERSION IS A DRAFT AND NEEDS DISCUSSION.

Rationale

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.

Git

The Java packaging team uses Git on Salsa as the version control system (VCS). All team maintained packages SHOULD use 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.

The debian/watch file 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 field 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.


CategoryJava