Skip to content

development.md

Latest commit

 

History

History
158 lines (118 loc) · 4.85 KB

development.md

File metadata and controls

158 lines (118 loc) · 4.85 KB

Development Guide

Note about scripts directory

The scripts directory directly contains a "catch-all" command called ubik, which is used to dispatch various subcommands in this project. This script comes from the Bashy-lib project, see which for helpful advice about integrating it into your shell environment.

Building

$ ubik dev build
...
Build complete!
$

By default, dev build deposits a runnable build in the directory out, directly under the top-level source directory. The script takes other options; dev --help for details.

ubik dev clean does what you (presumably) expect.

Linting Etc.

$ ubik dev lint
...
No linter errors! Yay!
$

There are also some tools which adjust source files to be in a standardized form:

  • ubik node-project fix-package-json — Derives intra-project dependencies from the actual source files, and updates each module's package.json to match. It actually entirely rewrites the file with project-standard boilerplate and formatting.
  • ubik node-project reflow-jsdoc — Reflows (fixes line breaks on) all the documentation comments in the source tree. Note: After running this, please double-check the results before committing, as this tool might produce results that indicate a need for the tool itself to be improved.
  • ubik node-project sort-imports — Sorts and arranges import lines into a project-standard form.

Testing

Unit tests

Unit test files live in directories named tests directly under each local package. They use Jest for both test definitions (describe(...), test(...)) and assertions (expect(...)...).

$ ubik run-tests
...
No errors! Yay!

Integration tests

Integration tests live in the top-level project directory tests. To run them:

$ ubik run-tests --type=integration
...
No errors! Yay!

You can also run ./tests/run-all, which provides options that can be useful depending on context. ./tests/run-all --help for details.

The run-tests script

The run-tests script takes other options; run-tests --help for details. Beyond the above, TLDR:

  • run-tests --do=build to do a build first, for convenience.
  • run-tests --type=unit-coverage to generate a unit test coverage report.
  • run-tests --type=unit-debug to enable interactive debugging while running the unit tests.

Running

Run out of the built out directory

This will run the system using the example configuration defined in etc/config, which includes a self-signed certificate for localhost, which might satisfy your local web browser.

$ ubik dev run
...

The run target of dev lets you pass arbitrary arguments to the server, by using the --run[] option, and it also makes the default dev target be run. TLDR very useful:

  • dev --run[]='--node-opts --inspect --' or dev --run[]='--node-opts --inspect=<arg>' -- — Pass an inspect option to Node (to start the inspector/debugger immediately).

You can also do a build first:

$ ubik dev build run
...

Recognized signals:

  • SIGHUP — Does an in-process system reload. (The system shuts down and then re-runs from near-scratch.)
  • SIGUSR1 — Starts the Node inspector/debugger, listening on the usual port. (This is a standard signal recognized by Node. Just noting it here as a reminder or perhaps a TIL.)
  • SIGUSR2 — Produces a heap snapshot file. Look in the log for the file name. (Writes to the current directory if it is writable, and falls back to the value of environment variables $HOME or $TMPDIR, finally trying /tmp as a last-ditch effort. The file can be inspected using the "Memory" panel available in the Chrome developer tools. Note: Node documentation claims that a process needs additional memory of about the same size as the heap being dumped; if the memory is not available you might find that your OS has killed the process before it completes the snapshot.
  • SIGINT and SIGTERM — Shuts down as cleanly as possible. (Note: SIGINT is usually what gets sent when you type ctrl-C in a console.)

Releasing

Use the script update-version will change the main version number, and prepare the CHANGELOG file for release.

$ ubik update-version 123.45.6

Updating Allowed Node Versions

The project has checks to make sure only vetted versions of Node are used to build and run the project.

To update what Node versions are allowed when building:

  • Update the check-dependency regex in the file scripts/lib/lactoserv/_prereqs.

To update what Node versions are allowed when running:

  • Update the --runner-versions= list in the file scripts/lib/lactoserv/dev.
Copyright 2022-2025 the Lactoserv Authors (Dan Bornstein et alia).
SPDX-License-Identifier: Apache-2.0