Little tutorial for JS-Team beginners.

The tools

To package node/javascript modules, you need at least:

Little howtos

Little schroot/sbuild howto

1. To build a minimal Debian unstable environment, you can use this:

$ sudo sbuild-createchroot unstable /srv/chroot/unstable-amd64-sbuild

2. To update it:

$ sudo sbuild-update unstable-amd64-sbuild -u -g -a -r

3. List built schroot

$ sudo schroot --list

Schroot improvements

1. Save bandwith using apt-cacher-ng

2. Use tmpfs to increase build speed

Little salsa howto

You need to generate a token in Salsa settings (check all checkboxes). Copy its value into ~/.devscripts:


Verify that it works:

$ salsa whoami
Id      : 1234
Username: myaccount-guest
Name    : My Name
Email   :
State   : active

You must also be member of js-team group. Verify this:

$ salsa list_groups
Id       : 2099
Name     : Debian JavaScript Maintainers
Full path: js-team

You must also set your public GPG key in your Salsa account.

Packaging walkthrough

Working with existing packages

1. Clone locally the package:

$ salsa --group js-team co node-temporary
$ cd node-temporary

Of course you need to configure salsa(1) with a valid GitLab token.

2. Verify debian/gbp.conf to not import upstream .gitignore. It may contain:

   1 [import-orig]
   2 filter = [ '.gitignore', '.git/*', '.git', '.travis.yml' ]
   4 [import-dsc]
   5 filter = [ '.gitignore', '.git/*', '.git', '.travis.yml' ]

3. Verify that debian/watch is compliant with npmjs registry:

$ debcheck-node-repo && echo OK

If result is bad, investigate manually. If upstream forgot to insert tags in its repository, please open an issue: it is better to use source repository than npm registry (which may contain some generated files)

4. Update the package:

$ uscan
$ gbp import-orig --pristine-tar ../node-temporary_9.9.9.orig.tar.xz

5. Fix debian/* files, then push the result:

$ git push origin master upstream pristine-tar
$ git push --tags

Always visit Debian Tracker and check work to do for this package.

Switch test and install to pkg-js-tools

pkg-js-tools provides hooks for auto-configuration, auto-test and auto-install and also autopkgtest.

To enable it:

Write good tests

Using pkg-js-tools, you just have to examine package.json (scripts -> test) to find upstream test and write it in debian/tests/pkg-js/test. Example:

$ cat debian/tests/pkg-js/test
mocha -R spec --timeout 10000 test/

See pkg-js-tools full example for more.

If upstream test is launched using mocha, don't hesitate to increase timeout (default is 2000 which is often too short for Debian-CI machines).

If debian/tests/pkg-js/test does not exist, pkg-js-tools will automatically add a minimal test (node require(".")).

Don't forget to remove debian/tests/control and debian/tests/require if exists.

Fully test your package

Dependencies test

Launch test in a minimal and up-to-date unstable environment to verify that all needed packages are declared in debian/control:

sbuild -j5 --no-apt-update -d unstable --no-clean-source --run-lintian --lintian-opts='--color always --display-info --display-experimental --pedantic'

or using gbp:

$ gbp buildpackage --git-ignore-branch --git-builder="sbuild -j5 --no-apt-update -d unstable --no-clean-source --run-lintian --lintian-opts='--color always --display-info --display-experimental --pedantic'" --git-export=WC

This also launches lintian. Check the result and fix all errors/warnings (or override them only if this is a false positive) and take care of other lintian checks.

Result test

pkg-js-tools helps to write good autopkgtest. If you write them yourself, remember that you must test installed files, not source ones. Launch autopkgtest (example with schroot):

$ autopkgtest -B ../*.deb -- schroot unstable-amd64-sbuild

and check result. By default, pkg-js-autopkgtest copies only test* files. If some other are needed, creates debian/tests/pkg-js/files and list all needed test files. Example:

$ cat debian/tests/pkg-js/files

URLs test

Simply launch duck in the Debian source directory and check the result.

Clean test

Launch 2 times dpkg-buildpackage -us -uc. If build files are not cleaned, the second will fail. If so, set them in a debian/clean. Example:

$ cat debian/clean

Starting a new package

First you may check if needed dependencies exists. Example to build ldapjs:

$ npm2deb depends ldapjs
NPM                                               Debian
ldapjs (1.0.2)                                    None
├─ asn1 (0.2.3)                                   node-asn1 (0.2.3-1)
├─ assert-plus (^1.0.0)                           node-assert-plus (1.0.0-1)
├─ backoff (^2.5.0)                               None
├─ bunyan (^1.8.3)                                None
├─ dashdash (^1.14.0)                             node-dashdash (1.14.1-2)
├─ dtrace-provider (~0.8)                         None
├─ ldap-filter (0.2.2)                            None
├─ once (^1.4.0)                                  node-once (1.4.0-3)
├─ vasync (^1.6.4)                                None
└─ verror (^1.8.1)                                node-verror (1.10.0-1)

Build dependencies:
NPM                                               Debian
faucet (0.0.1)                                    None
istanbul (^0.4.5)                                 node-istanbul (0.4.5+ds-4)
node-uuid (^1.4.7)                                node-uuid (3.3.2-2)
tape (^4.6.2)                                     node-tape (4.9.1-1)

Here, we can see that 5 modules are missing in Debian to package it: node-backoff, bunyan, dtrace-provider, ldap-filter and vasync. A quick analysis shows that at least ldap-filter could be embedded.

Then look at dependencies. Example with vasync:

$ npm2deb depends vasync
NPM                                               Debian
vasync (2.2.0)                                    None
└─ verror (1.10.0)                                node-verror (1.10.0-1)

Build dependencies:
NPM                                               Debian
nodeunit (0.8.7)                                  node-nodeunit (0.11.2+ds3-2)
tap (~0.4.8)                                      node-tap (12.0.1+ds-1)

This package can be built in Debian. Let's do it:

$ npm2deb create vasync

When all is OK and package builds well and lintian is clean, create a git repo:

$ cd node-vasync-2.2.0
$ git init
$ gbp import-dsc ../path/to/node-vasync_2.2.0-1.dsc

Then, you can push it using salsa(1) in the root of Debian source tree.

If your level access in js-team is only "developer", ask to a maintainer to create repo first, then no need to add --tagpending or --desc (added by maintainer using salsa create_repo --tagpending --desc node-<npm-name>).

$ salsa --group js-team --tagpending --desc push_repo .

If you want to push in your personal area, simply launch:

$ salsa --desc push_repo .