opensource.google.com

Menu

Docs

JavaScript

go/thirdpartyjavascript

This describes JavaScript-specific guidance for checking code into //piper/third_party.

IMPORTANT: Read go/thirdparty first.

General policies

NOTE: You should apply these changes on the initial checkin, even though it may mean your code is not “pristine.”

IMPORTANT: Using third-party JavaScript code that contains license text or copyright notices requires special treatment in the JavaScript source.

Since the Google JavaScript compiler strips out most comments in .js and .css source files, JavaScript files with license and copyright comments require special treatment. Even ‘notice’ licenses, which are usually considered not very strict in most respects, require the special @license JsDoc tag so that the notice is preserved. This is because JavaScript is distributed in its source form when it is used by browsers.

JavaScript source code should go into //third_party/javascript/packagename directories.

New third-party JavaScript package code reviews should be cc’ed to both emailremoved@ and emailremoved@ to ensure prompt, assigned reviews.

To preserve a block of text in a JavaScript source file, wrap the desired text in a JsDoc comment and supply the special @license tag. If the source already includes a JsDoc comment with a @preserve tag, that is sufficient as well.

/**
 * @license
 * Copyright 2008 SomeThirdParty.
 * Here is the full license text and copyright
 * notice for this file. Note that the notice can span several
 * lines and is only terminated by the closing star and slash:
 */
var foo = /...
function someThirdPartyFunc() *
  /...
}

If you include a license/preserve block, the JS Compiler will output the contents of the block in the compiled output of any js_binary rule. You should examine the compiled output and make sure the license block is present and legible.

Add a @license block for JavaScript released under a ‘notice’ license

If the original source code is under a notice license but the source files lack license and copyright info, you should add an @license block containing, at a minimum, a copyright statement and the full license text.

NOTE: If the source files have license and copyright info, but it doesn’t meet the minimum “copyright statement and full license text,” you should add that missing minimum information.

JavaScript @externs and TypeScript .d.ts files are an exception: since they are never served to the user, [they do not need a @license block*.

Legacy third_party/javascript packages created before the @license tag

Prior to 2008-4-10, the @license JsDoc tag did not exist and the ThirdParty team recommended that that JavaScript files containing notices remain uncompiled. This restriction has been lifted. If you maintain or depend on a js_library file with do_not_compile in the name, see if you can work with the authors to embed copyright and license information in an @license tag. This will allow your users to benefit from the faster download times of compiled JavaScript.

Caveat for JavaScript code for use in monitoring consoles

The //piper/…/third_party tree exists to contain third-party JavaScript code for use in monitoring consoles. It has a separate location in Piper so that it will be pushed out to production along with the rest of the monitoring configs. Packages in //piper/…/third_party still need to follow the general guidelines above, with the exception that the BUILD file need not contain any real build rules, just the comment sections from the latest BUILD file templates and a file-scope licenses() directive.

Importing (L)GPL JS libraries

You may add (L)GPL JS libraries to //piper/third_party/javascript, but if you do so they MUST NOT be compiled as part of a build rule. In order to meet the requirements of the (L)GPL, the correct way to include your script is via a SCRIPT tag. Your BUILD file will therefore simply export the files. E.g.:

filegroup(
   name = "my_amazing_library",
   srcs = glob(["*.js"]),
)

You may then include this as a data dependency of another target.

Note that including an (L)GPL library will have legal impact on your product. In particular:

  1. You will be required to make sure the unobfuscated source to the LGPL portion is available (pointing to someone else’s copy is not enough), and the license is available as well.

  2. Users will be allowed to modify your product, and reverse engineer it for the purpose of debugging those modifications.

You cannot prevent this (and go/uTos does not), and you must make sure if you are not on go/uTos that any TOS you have does not violate this by banning reverse engineering without an open source license override.

Multiple versions

go/oneversion applies to javascript libraries. emailremoved@ is the only group that can grant exemptions to this policy. Reviewers: any time you see a multiple_versions section in the METADATA file, that approval field MUST contain a link to the emailremoved@ thread where the exception was granted. go/oneversion is the source for truth for the current policy, so defer any questions to that document and emailremoved@. See the section on node.js modules for special versioning rules for those imports.

TypeScript

For the purposes of this policy, TypeScript code is treated exactly as JavaScript code would be. TypeScript is checked in underneath //piper/third_party/javascript as .ts files and transpiled to JavaScript using ts_library BUILD rules (or ng_module, or ts_declaraton, as appropriate). .d.ts files are exempt since they only contain type definitions and are never distributed to users, similar to @externs files for JavaScript.

Note that TypeScript code, in addition to an @license tag, requires an empty line after the initial file comment.

/**
 * @license The license of the code.
 */

// Note the empty line above.
class X { }

DefinitelyTyped type definitions, i.e. type definitions that are developed separately from the actual implementation code, please see //piper/third_party/javascript/typings.

In addition to emailremoved@, please contact emailremoved@ with any issues.

NodeJS / NPM modules

NodeJS modules live in //piper/third_party/javascript/node_modules. See go/nodemodulesingoogle3 for context about multiple versions for npm packages. See here for a deeper dive discussing npm packages.

NOTE: Using npm in a package outside of google3? There’s a tool for making license checking easier!

Except as otherwise noted, the content of this page is licensed under CC-BY-4.0 license. Third-party product names and logos may be the trademarks of their respective owners.