Skip to content

Latest commit

 

History

History
82 lines (52 loc) · 5.84 KB

amp-versioning-policy.md

File metadata and controls

82 lines (52 loc) · 5.84 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, it may be necessary to remove an existing feature or API. Such breaking changes must follow the following AMP deprecation process prior to removal.

Deprecations must be publicly discussed and provide significant user benefit that justifies additional work for page developers.

The process for deprecations is similar to the process for significant changes, but has some unique requirements:

  • File an Intent-to-Deprecate (I2D) issue describing the feature that is being deprecated, the motivation for deprecating it, and the plan for deprecating/removing the feature.
    • If you intend to remove the feature immediately after the warning period described below you may make your Intent-to-Deprecate issue an Intent-to-Deprecate-and-Remove issue (by modifying the title and adding the INTENT TO REMOVE label to it).
    • Otherwise if you do not have a concrete timeline for removal you may file a separate Intent-to-Remove (I2R) issue to track removal of the feature.
  • Allow at least 2 weeks of open discussion after the I2D is created before proceeding with the deprecation of the feature.
  • The deprecation and removal requires approval from at least 3 members of the Approvers Working Group.
  • Apply new behavior to old content in a way that minimizes breakage.
  • Announce the deprecation on the mailing list and on Slack
  • Start warning for pages that might break via the developer console.
  • Give developers at least 6 weeks after your deprecation warning is in production to apply changes before removing the feature.
  • If you did not include removal in your I2D, file a separate Intent-to-Remove (I2R) when you are ready to remove the deprecated feature.

If an underlying backend service has itself been turned down, then the given component or integration may be neutered immediately without breaking the validation.

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 [email protected] mailing list and on Slack.

Fixes that address security or privacy concerns may in some cases only be announced after the change was rolled out.