Skip to content

Latest commit

 

History

History
74 lines (47 loc) · 4.31 KB

amp-versioning-policy.md

File metadata and controls

74 lines (47 loc) · 4.31 KB
Raw

AMP versioning and deprecations policy

Goals

  • Reduce overall JS URL entropy. AMP aims to provide as few versions of the JS library and extensions as possible to improve cache hit rates for these requests.
  • Avoid breaking existing pages.
  • Keep all users of AMP on secure and updated versions of the library.
  • Enable all AMP developers to keep their AMP pages up-to-date.

Versioning

  • The AMP JS library and its extensions are versioned. There is also an AMP release that corresponds to the precise code. Each major and minor version may correspond to many AMP releases.
  • AMP is released about once per week and each release has a unique version number. With each release, AMP pages are rendered with the latest code for the respective major/minor versions of the AMP JS library and extensions.

AMP JS library

The AMP JS library is distributed via its major version only. The major version is expected to change rarely if ever (on the order of less than once per year).

AMP extensions

Each AMP extension is versioned independently. Publishers of AMP documents can choose the major and minor version of an extension; they cannot choose the patch version.

  • Extension minor versions may be changed for breaking behavior changes without breaking API changes.
  • Extension major versions must be changed for any breaking API changes.

Breaking changes

Breaking changes must be implemented in a new major or minor version of an extension or (more rarely) the AMP JS library, except in rare cases1.

Breaking changes are defined as:

  • Changes to exposed API semantics, e.g. supported attributes in an AMP extension.
  • Changes to CSS included in AMP that are not backward compatible.
  • Changes to the DOM structure (elements, attributes and attribute values) generated by AMP extensions that are not backward compatible.
  • Changes to AMP validation rules that are not backward compatible.

The following are not considered breaking changes:

  • Changes to elements and their children including their CSS if the element name starts with i-.
  • Changes to attribute and class names starting with i- (but this doesn't mean that CSS backward compatibility may be broken with this mechanism, which would be considered a breaking change).

1The following exceptions may be implemented without a new version:

  • Changes required to maintain the security of AMP pages.
  • Changes that affect fewer than 0.1% of crawler-accessible AMP pages.
  • Changes that follow the deprecations process below.

Deprecations

In rare cases, the AMP project may decide that an existing feature or API must be removed. Such breaking changes must follow the AMP deprecations process prior to removal. Deprecations must be publicly discussed and provide significant user benefit that justifies additional work for page developers.

Process:

  • Create INTENT TO IMPLEMENT issue.
  • Allow for at least 2 weeks of open discussion.
  • Wait for 3 approvals from core committers.
  • Announce change on the mailing list.
  • Start warning for pages that might break via the developer console.
  • Give developers 6 weeks to apply changes.
  • Apply new behavior to old content in a way that minimizes breakage.

Version deprecations

Old versions of the AMP JS library and extensions may eventually be declared invalid by the AMP Validator. Such changes are breaking and must follow the deprecations process above. Additional rules also constrain the timelines of version deprecations:

  • A version must not be deprecated until a new version is released and stable for at least 1 month.
  • A version must not be invalidated until it has been deprecated for at least 1 year.

The binaries of old versions must not be removed except in the case of security issues.

Announcements

Changes that may break existing pages (including those where the number of broken pages is assumed to be very small) should be announced via the amphtml-announce@googlegroups.com mailing list. Sometimes such changes are not anticipated upfront in which case announcements should still be sent to let websites know.

Security fixes may in some cases only be announced after the change was rolled out.