Skip to content

Latest commit

 

History

History
138 lines (101 loc) · 8.15 KB

DEVELOPING.md

File metadata and controls

138 lines (101 loc) · 8.15 KB
Raw

Development on AMP HTML

Slack and mailing list

We discuss implementation issues on [email protected].

For more immediate feedback, sign up for our Slack.

Starter issues

We're curating a list of GitHub "starter issues" of small to medium complexity that are great to jump into development on AMP.

If you have any questions, feel free to ask on the issue or join us on Slack!

Installation

  1. Install NodeJS.
  2. In the repo directory, run npm i command to install the required npm packages.
  3. run sudo npm i -g gulp command to install gulp in your local bin folder ('/usr/local/bin/' on Mac).
  4. edit /etc/hosts and map ads.localhost and iframe.localhost to 127.0.0.1.
  127.0.0.1               ads.localhost iframe.localhost

Build & Test

Command Description
gulp Runs "watch" and "serve".
gulp dist Builds production binaries.
gulp lint Validates against Google Closure Linter.
gulp lint --watch Watches for changes in files, Validates against Google Closure Linter.
gulp lint --fix Fixes simple lint warnings/errors automatically.
gulp build Builds the AMP library.
gulp clean Removes build output.
gulp css Recompile css to build directory.
gulp extensions Build AMP Extensions.
gulp watch Watches for changes in files, re-build.
gulp test Runs tests in Chrome.
gulp test --verbose Runs tests in Chrome with logging enabled.
gulp test --watch Watches for changes in files, runs corresponding test(s) in Chrome.
gulp test --watch --verbose Same as "watch" with logging enabled.
gulp test --saucelabs Runs test on saucelabs (requires setup).
gulp test --safari Runs tests in Safari.
gulp test --firefox Runs tests in Firefox.
gulp serve Serves content in repo root dir over http://localhost:8000/.
------------------------------- -----------------------------------------------------------------------

To fix issues with Safari test runner launching multiple instances of the test, run:

  defaults write com.apple.Safari ApplePersistenceIgnoreState YES

Saucelabs

Running tests on Sauce Labs requires an account. You can get one by signing up for Open Sauce. This will provide you with a user name and access code that you need to add to your .bashrc or equivalent like this:

export SAUCE_USERNAME=sauce-labs-user-name
export SAUCE_ACCESS_KEY=access-key

Also for local testing, download saucelabs connect (If you are having trouble, downgrade to 4.3.10) and establish a tunnel by running the sc before running tests.

Because of the user name and password requirement pull requests do not directly run on Travis. If your pull request contains JS or CSS changes and it does not change the build system, it will be automatically build by our bot @ampsauce. Builds can be seen on @ampsauce's Travis and after they finished their state will be logged to your PR.

If a test flaked on a pull request you can ask for a retry by sending the comment @ampsauce retry. This will only be accepted if you are a member of the "ampproject" org. Ping us if you'd like to be added. You may also need to publicly reveal your membership.

Manual testing

For testing documents on arbitrary URLs with your current local version of the AMP runtime we created a Chrome extension.

Repository Layout

  3p/             - Implementation of third party sandbox iframes.
  ads/            - Modules implementing specific ad networks used in 
  build/          - (generated) intermediate generated files
  build-system/   - build infrastructure
  builtins/       - tags built into the core AMP runtime
      *.md        - documentation for use of the builtin
      *.js        - source code for builtin tag
  css/            - default css
  dist/           - (generated) main JS binaries are created here. This is what
                    gets deployed to cdn.ampproject.org.
  dist.3p/        - (generated) JS binaries and HTML files for 3p embeds and ads.
                    This is what gets deployed to 3p.ampproject.net.
  docs/           - documentation
  examples/       - example AMP HTML files and corresponding assets
  examples.build/ - (generated) Same as examples with files pointing to the
                    local AMP.
  extensions/     - plugins which extend the AMP HTML runtime's core set of tags
  spec/           - The AMP HTML Specification files
  src/            - source code for the AMP runtime
  test/           - tests for the AMP runtime and builtins
  testing/        - testing infrastructure

Supported browsers

In general we support the 2 latest versions of major browsers like Chrome, Firefox, Edge, Safari and Opera. We support desktop, phone, tablet and the web view version of these respective browsers.

Beyond that the core AMP library and builtin elements should aim for very wide browser support and we accept fixes for all browsers with market share greater than 1 percent.

In particular, we try to maintain "it might not be perfect but isn't broken"-support for the Android 4.0 system browser and Chrome 28+ on phones.

Eng docs

We also recommend scanning the spec. The non-element part should help understand some of the design aspects.

AMP Dev Channel (Experimental)

AMP Dev Channel is a way to opt a browser into using a newer version of the AMP JS libraries.

This release may be less stable and it may contain features not available to all users. Opt into this option if you'd like to help test new versions of AMP, report bugs or build documents that require a new feature that is not yet available to everyone.

To opt your browser into the AMP Dev Channel, go to the AMP experiments page and activate the "AMP Dev Channel" experiment.

Code of conduct