Differences between revisions 1 and 23 (spanning 22 versions)
Revision 1 as of 2011-10-15 06:18:00
Size: 1494
Editor: DavidPaleino
Comment: first draft
Revision 23 as of 2020-09-22 11:25:39
Size: 2358
Editor: ?yadd
Comment: Add link to transition policy
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= Debian Javascript Policy = ## page was renamed from Teams/Javascript/Policy
## page was renamed from Teams/pkg-javascript/Policy
{{{#!wiki caution
'''This document is still work in progress.'''
Line 3: Line 6:
This page describes the policy that packages with javascript libraries should follow. Please check the [[https://lists.alioth.debian.org/pipermail/pkg-javascript-devel/|mailing list archives]] for the latest discussions about it.
}}}
Line 5: Line 9:
== Package naming == = Introduction =
Line 7: Line 11:
Given a '''foo''' library, packages must be named according to the following rules: This page describes the policy that packages with Javascript libraries should follow.
Line 9: Line 13:
 * if the library is usable from within a web-browser, the ''binary'' package name '''must''' be called '''libjs-foo''', and the ''source'' package name '''should''' be called '''foo.js''';
 * if the library is usable from within the NodeJS framework, the ''binary'' package name '''must''' be called '''libnode-foo''', and the ''source'' package name '''should''' be called '''node-foo''';
 * if the library is usable both from a web-browser ''and'' from NodeJS, it should generate ''two binary packages'', each called as described above.
== Policy ==
Line 13: Line 15:
Please remember that it's preferable if you name the repository after the source package name (i.e. ''foo.js.git'' for foo.js and ''node-foo.git'' for node-foo). This isn't a hard requirement though. See also [[Javascript/Transitions/Policy|Transition Policy]]
Line 15: Line 17:
== Paths ==
=== libjs-foo ===
The scripts should be installed to `/usr/share/javascript/foo/`.
 0. given a '''foo''' library, binary package '''must''' be called '''libjs-foo''' and the ''source'' package name '''should''' be called '''foo.js''';
Line 19: Line 19:
=== libnode-foo ===
The scripts should be installed to `/usr/lib/nodejs/` or `/usr/lib/nodejs/foo/`. The choice depends whether the library is contained in a single file or in multiple files. In case the latter is chosen, `/usr/lib/nodejs/foo/` should contain a `index.js` pointing to the main library file. This could be either a symlink or a code snippet like:
 0. '''should''' recommend ''javascript-common'' in debian/control
Line 22: Line 21:
{{{
module.exports = require('foo.js');
}}}
 0. '''should''' be installed to `/usr/share/javascript/foo/`
 
 0. '''should''' ship a ''minified'' version for each script, generated at build time (use [[../Nodejs#uglifyjs|UglifyJS]] or [[../Nodejs#terser|terser]] for this purpose)

 0. '''should''' generate a '''node-foo''' binary package if the script is usable also for [[../Nodejs|Nodejs]].

Please remember that it's preferable if you name the repository after the source package name (i.e. ''foo.js.git'' for foo.js). This isn't a hard requirement though.

=== Proposal ===

Today most of JS packages does not follow the naming policy. I suggest this:
 0. Naming policy. Given a '''foo''' library
   * a browser-only package '''must''' be called libjs-foo
   * a node-only package '''must''' be called node-foo
   * for a both browser/node binary, browser binary package '''must''' be called '''libjs-foo''', node binary package '''must''' be called '''node-foo''' and the ''source'' package name '''should''' be called '''foo.js''';

== Exclude auto-generated files from source ==
Strict application of '''DFSG''' requires files generated from source in upstream tarball to be excluded, unless it is possible to regenerate the files and prove they are identical to the ones in the tarball.

Minified files and browserified files are examples of such files that '''could''' be excluded for that reason. A convenient way to achieve this is to use the '''Files-Excluded''' field in '''debian/copyright''', for more information please see [[../Repacking|repacking]] and [[UscanEnhancements|uscan enhancements]].

----

CategoryPackaging

This document is still work in progress.

Please check the mailing list archives for the latest discussions about it.

Introduction

This page describes the policy that packages with Javascript libraries should follow.

Policy

See also Transition Policy

  1. given a foo library, binary package must be called libjs-foo and the source package name should be called foo.js;

  2. should recommend javascript-common in debian/control

  3. should be installed to /usr/share/javascript/foo/

  4. should ship a minified version for each script, generated at build time (use UglifyJS or terser for this purpose)

  5. should generate a node-foo binary package if the script is usable also for Nodejs.

Please remember that it's preferable if you name the repository after the source package name (i.e. foo.js.git for foo.js). This isn't a hard requirement though.

Proposal

Today most of JS packages does not follow the naming policy. I suggest this:

  1. Naming policy. Given a foo library

    • a browser-only package must be called libjs-foo

    • a node-only package must be called node-foo

    • for a both browser/node binary, browser binary package must be called libjs-foo, node binary package must be called node-foo and the source package name should be called foo.js;

Exclude auto-generated files from source

Strict application of DFSG requires files generated from source in upstream tarball to be excluded, unless it is possible to regenerate the files and prove they are identical to the ones in the tarball.

Minified files and browserified files are examples of such files that could be excluded for that reason. A convenient way to achieve this is to use the Files-Excluded field in debian/copyright, for more information please see repacking and uscan enhancements.


CategoryPackaging