Overview

JavaScript code used for the web needs special consideration to ensure that it meets the high standards expected of all code shipped by Fedora, while still being useful and complying with conventions already used on millions of websites. Additionally, certain libraries typically used on the web can also be useful in a server-side context (by nodejs or rubygem-execjs), so it’s important to package JavaScript so it meets the standards required of locally executed code as well.

Please note that this section really only applies to JavaScript libraries intended for use on the web. Server-side JavaScript runtimes like Node.js Packaging:Node.js[have their own guidelines], and software like GNOME which embeds JavaScript for extensions have their own directories and policies as well.

Rationale

Duplication

We have a standard to avoid Packaging:Guidelines#Duplication_of_system_libraries[duplication of system libraries]. This applies as much to JavaScript libraries as it does to C, python, Java, and any other programming language. The main concern is security. JavaScript code is not vulnerable to buffer overflows like C but it can be subject to attacks from malicious data that attempts to send the user to alternate web sites, steal their information, or execute code via jsonp requests to an alternate server. Duplicating third party libraries in an application leads to these problems sticking with an application even after the upstream library has fixed the issues. It is therefore prohibited.

There are also some JavaScript libraries which are intended to be used on the local system, not served via a web server to a browser. These libraries clearly have all the standard reasons to avoid duplication.

Licensing

It is common to see third-party applications consuming multiple JavaScript libraries. When all of these libraries are placed together in one directory, there is little information to tell what the relationship is between the files. This leads to problems when incompatible licenses are found. For instance, consider a situation where Foo.js is licensed with Apache Software License-2.0, Bar.js and Baz.js licensed with LGPLv2+, and Qux.js with MIT. We have to then audit the code in Foo.js to determine what symbols are potentially being used in other files, and then audit Bar.js and Baz.js to see if those symbols are being used there.

Having separate packages for each library makes diagnosing these problems much easier.

Naming Guidelines

The name of a JavaScript library package must start with js- then the upstream name. For example: js-jquery.

BuildRequires

To ensure the presence of the necessary RPM macros, all packages that provide JavaScript in %{_jsdir} must have:

BuildRequires:  web-assets-devel

Requires

To ensure the availability of the necessary directories, all packages that provide JavaScript in %{_jsdir} must have:

Requires:  web-assets-filesystem

JavaScript packages must not have Requires on any HTTP daemon-specific configuration package, such as web-assets-httpd, since they could be used by any HTTP daemon.

RPM Macros

Macro Normal Definition Notes

_jsdir

%{_datadir}/javascript

The directory where JavaScript libraries are stored

Install Location

  • If a JavaScript library can be executed locally or consists purely of JavaScript code, it must be installed into a subdirectory of %{_jsdir}.

  • If a package contains JavaScript code, but is never useful outside the browser (e.g. if it is some sort of HTML user interface library) it may instead install to %{_assetdir}. For more information, see Packaging:Web_Assets[the Web Assets guidelines].

  • If a package contains JavaScript code that is only used as part of a web application, and it is not useful to any other applications whatsoever, it may continue to ship that code along with the application. However, that does not absolve it from complying with the rest of these guidelines.

  • If a package contains JavaScript code that is not useful on the web, but only in locally run software (e.g. Packaging:Node.js[Node.js] or GNOME shell extensions), it should use the appropriate directory for its runtime, not %{_jsdir}.

Server Location

JavaScript code is included as part of the general Packaging:Web_Assets[Web Assets framework]. Therefore, %{_jsdir} is available on Fedora-provided web servers by default at /_sysassets/javascript/.

For instance, jQuery may be installed in %{_jsdir}/jquery/jquery-min.js, so web applications that need to use it can simply include this HTML tag:

<script type="text/javascript" src="/_sysassets/javascript/jquery/jquery-min.js"></script>

Regardless, web applications may want to make subdirectories of %{_jsdir} available under their own directory via aliases or symlinks for compatibility purposes or to eliminate needless deviation from upstream.

Compilation/Minification

If a JavaScript library typically is shipped as minified or compiled code, it must be compiled or minified as part of the RPM build process. Shipping pre-minified or pre-compiled code is unacceptable in Fedora.

The compiler or minifier used by upstream should be used to compile or minify the code. If the minifier used by upstream is unable to be included in Fedora, an alternative minifier may be used. See this page for a list of known problem areas and suggestions for workarounds.

Additionally, the uncompiled/unminified version must be included alongside the compiled/minified version.

Minified JavaScript is not useful for JavaScript run locally, as the entire point of minification is to reduce HTTP transfer times. Therefore, JavaScript not intended for the web (e.g. for Node.js or GNOME Shell extensions) must not be minified.

Static Inclusion of Libraries

A single minified JavaScript file may contain bundled code from other JavaScript libraries. This may be to reduce HTTP transfer times for incredibly common libraries, like jQuery, which bundles sizzle.js, or when web applications only utilize parts of large JavaScript libraries like Dojo.

JavaScript files intended for the web may include the source of other JavaScript libraries (in whole or in part) without an exception from the FPC, provided the following conditions are met:

  • The bundled library must be shipped as a separate package in Fedora, which also meets these guidelines.

  • The package that statically includes the library must use the code from that separate package. It must not bundle its own version of the library.

  • The package that statically includes the library must include virtual provides in the form Provides: js-includes(`)` for all libraries it statically includes in this fashion. web-assets-devel provides a %js_includes macro that will automatically add the version present in the mock buildroot to the virtual provides. To use it, just add +%js_includes + anywhere before %prep in your spec file.

Again, this is only useful for the web. Locally used JavaScript runtimes (like Node.js or GNOME Shell extensions) must have a mechanism for utilizing libraries, and they are not permitted to utilize this exception to the Packaging:No_Bundled_Libraries[standard bundled libraries policy].

Wrappers for Other Languages or Environments

Sometimes there may exist a simple wrapper from a foreign language (like Ruby via rubygem-execjs or Java via rhino) or server-side JavaScript environment (like Node.js) to a pure JavaScript library. Such packages should delete the bundled library code and instead point to and Require the code provided by the primary Fedora package for that library.

Node.js Modules that contain browser/pure-JS components

Some Node.js modules include parts that can be used in the browser or by other server-side JavaScript engines. Such packages should be shipped as one SRPM that contains two packages:

  • One js-foo package that contains the pure JavaScript portion, following these guidelines.

  • One nodejs-foo package that contains the Node.js module portion, following the Packaging:Node.js[Node.js guidelines]. This may symlink to the necessary files or directories of the js-foo package.