1494
Comment: first draft
|
2358
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
given a foo library, binary package must be called libjs-foo and the source package name should be called foo.js;
should recommend javascript-common in debian/control
should be installed to /usr/share/javascript/foo/
should ship a minified version for each script, generated at build time (use UglifyJS or terser for this purpose)
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:
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.