Skip to content

Latest commit

 

History

History
179 lines (121 loc) · 9.52 KB

conventions.md

File metadata and controls

179 lines (121 loc) · 9.52 KB
Raw

video.js Plugin Conventions

When we refer to "conventional video.js plugins" we are not referring to any official, codified standard (e.g. ECMAScript or HTML5). Rather, we are referring to the rules used internally at Brightcove in developing both open-source and proprietary plugins for video.js.

These rules are by no means required for community plugins. You can write plugins in whichever way you choose. However, these rules are recommended, as we want to foster consistency within the video.js ecosystem.

This document and the Yeoman generator it is part of are provided as open-source for the good of the community. If you don't agree with these conventions, by all means follow your preferences in your plugin projects!

Table of Contents

Rules Summary

All conventional video.js plugins must:

  • ...be npm packages.
  • ...have automation available through npm scripts.
  • ...implement the core set of npm scripts.
  • ...be written in ES6 and pass videojs-standard linting.
  • ...have tests.
  • ...never check build artifacts into master branch (or equivalent) history the repository.

Packaging and Dependencies

All conventional video.js plugins must be npm packages.

Plugins should be as self-contained as possible, so the only dependency by default is video.js and global, providing access to global variables.

Development dependencies will include many packages related to developing, building, and testing a conventional video.js plugin.

Structure

Folder/Filename Optional? Generated? Description
dist/ Build output for browser/script tag usage, ignored by Git.
docs/ ✓ Any documentation beyond README.md.
lang/ ✓ ? Any JSON language files for the plugin.
scripts/ ✓ Scripts used by tooling; not part of the source code!
src/ ✓ All source code.
src/js/ ✓ JavaScript source code.
src/plugin.js ✓ Plugin entry point.
test/ ✓ Unit tests.
scripts/karma.conf.js ✓ Karma configuration file.
test/plugin.test.js ✓ Default plugin test module.
.editorconfig ✓
.gitignore ✓
.npmignore ✓
.nvmrc ✓
CHANGELOG.md ✓ ✓
CONTRIBUTING.md ✓ ✓ Documents how developers can work on the plugin.
index.html ✓ ✓ An example of usage of the plugin. This can be used with GitHub pages as well.
LICENSE ✓ ? Defaults to MIT.
package.json ✓
README.md ✓ Documents what the plugin does and how to use it as a general user.

Optional?

  • ✓: The file/directory is not required to meet the rules in this document.

Generated?

Bear in mind, that multiple runs of the generator will prompt you for each conflicting file that exists before overwriting!

  • ✓: The file/directory is always generated by the generator.
  • ?: The file/directory may be generated, depending on options.
  • Otherwise, the file is never generated.

Automation

All automation for a conventional video.js plugin must be available through npm scripts.

The generator provides npm script automation for all aspects of plugin development. There is no need for a third-party build tool.

However, some developers may prefer to implement their build process with a tool like Gulp or Grunt and this is an accepted practice provided the core set of npm scripts are aliased to the appropriate command for your build tool. For example, if you're using grunt, your package.json might have:

"scripts": {
  "build": "grunt",
  "build:js": "grunt js"
}

There are many good reasons to standardize on npm scripts:

  • npm provides a unified interface while keeping implementation choices up to the individual developer or team.
  • Where a separate build tool is preferred, npm scripts can easily act as aliases to build tasks (e.g., "start": "gulp start-server").
  • npm is a common denominator (far more than build tools); so, CI servers, contributors, and other tools can use npm without worrying about the underlying tool.
  • Consistent npm script naming means contributors don't have to learn a new build tool or new set of commands when moving between plugin projects, lowering the barrier to contributions.

npm Core Scripts

All conventional video.js plugins must implement the core set of npm scripts.

All names are lower-case and use colons (:) as sub-task separators (multiple colons separate multiple levels of sub-tasks). Other scripts (e.g., sub-sub-tasks and pre*/post* scripts) will be created as well, but these are not documented here as they are not considered core scripts and are subject to change.

npm Script Optional Description
build Runs all build sub-tasks.
clean Cleans up all build artifacts.
docs ✓ Performs documentation tasks.
lint Lints all .js ES6 source file(s) using videojs-standard.
start Starts a development server at port 9999 with automatic background builds (see watch).
test Runs lint, builds tests, and runs tests in available browsers.
watch Watches .js and (optional) .scss sources and rebuilds on demand.

Coding Style

All conventional video.js plugins must pass videojs-standard linting.

In an effort to reduce guess work, improve maintainability, avoid stylistic bikeshedding, and simplify the code review process, we have a linter based on the popular standard project, named videojs-standard.

Its coding conventions are enforced in conventional video.js plugins via the npm run lint command.

videojs-standard assumes all code it evaluates is written in ES6. Therefore, it ignores build artifacts, which are written in ES5.

Testing

All conventional video.js plugins must have tests.

Testing is a critical element of any software project and it should be done in an environment as similar to production as possible. To that end, video.js plugin tests should be run in a browser.

Testing is performed with QUnit as the testing framework and Karma as the runner.

Writing Tests

All scripts containing tests must be named in the format *.test.js

The generator-provided test entry point is test/plugin.test.js (matching src/plugin.js). For simple plugins, this is typically sufficient.

For complex plugins with multiple modules/components, it might make sense to break up tests into multiple modules, too. How test modules are split up is really up to the developer, but the recommended practice is to have a test module for each source module. For example:

src/plugin.js :: test/plugin.test.js
src/foo.js :: test/foo.test.js
src/bar.js :: test/bar.test.js

When the build:test script is executed, all *.test.js files within test and sub-directories will be built into the output script (test/dist/bundle.js).

Testing with Karma

All the test automation uses single-run Karma sessions. npm test will launch all the matching browsers which Karma supports and run tests in them.

Testing in a Browser

During development, it may be more convenient to run your tests manually in a browser tab (i.e. through QUnit directly, not Karma). This can be achieved easily by running a development server with npm start and navigating to http://localhost:9999/test/.

Release

Versioning

Conventional video.js plugins must never check in build artifacts to the main branch (i.e. master) history in source control.

The "preversion" script will run npm test to enforce code quality and unit test passage before allowing the version to be bumped.

Publishing

Open-source plugins should use the most basic publishing process available - npm publish - which should be run after versioning. Closed-source plugins are left to their respective author(s) or organization.