Search Results
  1. ECMAScript
  1. ECMAScript Libraries
    1. Revision control
    2. README
    3. LICENSE
    4. index.js
      1. Package version
    5. Package metadata
    6. Tests
    7. Build products
    8. Coverage
    9. Analysis and style checking
      1. .editorconfig
      2. eslint
    10. Credentials
    11. Continuous integration

ECMAScript Libraries

This describes how to package and distribute ECMAScript (JavaScript) libraries. This does not cover applications, which do not need to be included as part of another application, although the package may contain utility executables for development use.

Libaries are typically distrbuted in a bundle of files called a package, which may contain the executable code, as well as development utilities, tests, and documentation.

Revision control

The package should be revision controlled, Git is highly preferred.

README

The package should contain a README with the following sections:

  1. Summary
  2. Example
  3. Documentation or link to documentation
  4. Index of files in the repository

LICENSE

For legal reasons in most every legal jurisdiction that uses computers, the copyright owners must give permission for other people to use the package. This should be done with a LICENSE file in the repository.

index.js

The library should have an exposed interface at an index.js file. This file indexes the objects available for applications and other libaries to use.

Package version

It should not be necessary to expose the package version to the application in an exported property.

In the event this is really necessary, make this a build step; write the current git tag (using git describe) to a file, which is imported.

Package metadata

Consumers of the library will typically go through a package repository that keeps track of releases and an ecosystem of package names.

For npm, use package.json, or a package.yaml file that's built into JSON at package-time.

Tests

The package should have. Except as needed to verify truly exceptional conditions that cannot be otherwise tested (network errors, etc), tests should test the public-facing interface at index.js.

Tests should cover common failure modes, including network failure.

Build products

With certain exceptions, do not check build products into source control. List build products in .gitignore and other files, so that they don't get checked in.

Exceptions include:

  • Products that must be generated by hand by particular individuals. For example, exporting a Photoshop file into a lossless png.
  • Source files for historical reference.
  • Build products that require additional hand-modification, for example, autogenerated lexer code. This should be automated if at all possible, for example, with a patch file.
  • Files that benefit developers and reading the repository for the first time. For example, an index of files, or a README.md generated from other files.
  • Project dependencies without a viable alternative for distribution. For example, some test suites.

Even in most of these cases, consider placing the files under an archive/ directory, or using git submodules.

If a platform requires build products be checked into source control, consider having a branch just for this purpose, e.g. master-build that tracks the current master branch. For targeting different platforms, create multiple such branches (e.g. master-build-nodejs, master-build-cjs, etc).

Coverage

Using a code coverage tool can help ensure that your tests exercise most all the functionality of your application.

Tests should call every function in every interface. Assertions need not be covered (for example, testing arguments, or sanity checks), but still might be warrented.

Analysis and style checking

Packages should use a small variety of style checking tools.

If you don't have a linter or style guide, then it would be unreasonable rejecting pull requests for bad style alone.

.editorconfig

Use a .editorconfig file to specify text expectations, including indentation, line endings, and character set.

eslint

For enforcing code style and testing for common bugs, use ESLint. Keep a .eslintrc.js file around.

Credentials

Do not store credentials in revision control. Write a test to ensure that example configuration files do not have anything looking like real authentication credentials.

Tests and development should be possible in offline use. Have a script that configures a completely local development environment for offline use, and keep a test that ensures this script works.

For shared development databases, provide a link to configuration files that can be downloaded.

Continuous integration

Use a CI tool to automatically run tests for commits, this can help ensure that pull requests pass tests, for example.

Do not include credentials, and avoid including data that is specific to a particular user, Git repository (this makes forks difficult, and in turn makes development difficult).