Jetpack/Design Guidelines

Goals

Jetpack is intended to improve the following areas of Firefox extensibility:

Compatibility

Large numbers of current addons require work at each major release to maintain compatibility. A major design goal for Jetpack is to provide a base set of functionality needed to extend the browser and create a stable set of interfaces around those features to eliminate these incompatibility problems. In a nutshell, Keep Addons Working Across Major Releases! for the benefit of end-users who like using addons and developers who don't want to chase more frequent Firefox and other product release trains.

Security

Currently, addons can "do anything" once installed. Jetpack is being designed to restrict, isolate, and sandbox the set of capabilities it provides to improve security for users, by extending to addons only the capabilities they need, restrict access to internal implementation details of those capabilities, and make their use of those capabilities more visible to code reviewers and users.

Usability

Historically, Firefox API design has been limited by the requirements of XPCOM/XPIDL and has not taken advantage of improvements in the expressiveness of the JavaScript language and achievements in API ergonomics by JavaScript libraries. Jetpack will provide a JS-only API with a strong focus on simplicity, productivity, and flexibility.

Principles

Jetpack APIs should be:

• simple, eschewing obfuscation
• minimal, providing functionality that meets common use cases, not every possible case
• easy to learn and use, even without documentation
• hard to misuse, whether intentionally or unintentionally
• consistent, both within each API and across the entire API set provided by Jetpack
  • similar object properties and method parameters should have similar names
  • similar method parameters should be in the same position in call signatures
• flexible, so adaptable to unanticipated use cases (although not at the expense of overgenericism)
• reusable, for use in higher-level and composed APIs
• completely specified, in Jetpack Enhancement Proposals (JEPs)
• completely documented, in Jetpack documentation

References

• Best Practices in Javascript Library Design
• API Design Matters
• How to Design a Good API and Why it Matters
• On API Design Guidelines
• Programmers Are People, too