Proposed ?JavaScript packaging policy, which adds provisions for parallel installation of different API versions, makes it more policy-like, and is in general more verbose (which may or may not be a good thing).


This page describes the packaging policy that for packages containing ?JavaScript libraries. The words must, should, may, required, recommended, and optional are used as described in section 1.1 of the Debian Policy Manual.

This policy deals primarily with ?JavaScript libraries that are meant to be executed in a browser environment. The policy for ?JavaScript libraries that are meant to be used with Node.js is described in the Node.js modules policy. Since some software may be used in either environment, both policies may be applicable to a single source package.

JavaScript Libraries

Binary packages of ?JavaScript libraries should declare a Recommends relationship with the javascript-common package. This will allow ?JavaScript packages to be accessible via HTTP from a supported web server under the /javascript directory.

Binary packages should ship a minified version of each script, generated at build time. UglifyJS (package node-uglify) may be used for this purpose.

API changes and parallel installation

Libraries sometimes change their API in incompatible ways, and software might depend on different API versions of the same library. Thus in order to allow multiple versions of the same library to be installed in parallel, different versions implementing different APIs should have different package names and install the library files in different places.

Normally, this should be done by placing a library named foo in a binary package called libjs-fooAPIVERSION (or libjs-foo-APIVERSION where libjs-fooAPIVERSION would be confusing, such as when foo ends with a digit), where APIVERSION is the API version for the library. As an example, if the library's version numbering follows the Semantic Versioning Specification (?SemVer), then APIVERSION would be the library's major version number if the major version number is non-zero. The APIVERSION for a library that does not follow ?SemVer may be different.

The package name should change by updating the APIVERSION when a newer version of the library makes incompatible API changes. API changes that do not result in incompatibility with software written for a prior version do not require a change in the package name.

Binary packages should install libraries under a subdirectory of /usr/share/javascript. The recommended location for a library name foo with a given API version is /usr/share/javascript/fooAPIVERSION, or /usr/share/javascript/foo-APIVERSION.

The source package name may also include the APIVERSION in its name.

A libjs-foo package may be provided that depends on a libjs-fooAPIVERSION package, and provides a symbolic link from /usr/share/javascript/foo to /usr/share/javascript/fooAPIVERSION.

If a library's API is not expected to change in an incompatible way, or if API compatibility is ensured by other means, then the library may be placed in a binary package called libjs-foo, and the library may be installed under /usr/share/javascript/foo.

NodeJS modules

If the library is also usable with Node.js, then the source package should also generate a node-fooAPIVERSION binary package. See the Node.js modules policy for more detail.

Source Code Repository

It is preferable if you name the repository after the source package name (e.g. foo.js.git for foo.js), but this is not a hard requirement.