Skip to content

Latest commit

 

History

History
207 lines (143 loc) · 12.8 KB

DEVELOPING.md

File metadata and controls

207 lines (143 loc) · 12.8 KB
Raw

Development on AMP HTML

Slack and mailing list

Please join our announcements mailing list. This is a curated, low volume list for announcements about breaking changes and similar issues in AMP.

We discuss implementation issues on amphtml-discuss@googlegroups.com.

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 npm i -g gulp command to install gulp system-wide (on Mac or Linux you may need to prefix this with sudo, depending on how Node was installed).
  4. Edit your hosts file (/etc/hosts on Mac or Linux, %SystemRoot%\System32\drivers\etc\hosts on Windows) 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[1] Runs "watch" and "serve". Use this for standard local dev.
gulp dist[1] Builds production binaries.
gulp dist --fortesting[1] Indicates the production binaries are used for local testing. Without this ads, tweets and similar use cases are expected to break locally when using minified sources.
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[1] Builds the AMP library.
gulp build --fortesting[1] Builds the AMP library and will read the AMP_TESTING_HOST environment variable to write out an override AMP_CONFIG.
gulp build --css-only[1] Builds only the embedded css into js files for the AMP library.
gulp clean Removes build output.
gulp css Recompile css to build directory.
gulp extensions Build AMP Extensions.
gulp watch[1] Watches for changes in files, re-build.
gulp test[1] Runs tests in Chrome.
gulp test --verbose[1] Runs tests in Chrome with logging enabled.
gulp test --nobuild Runs tests without re-build.
gulp test --watch[1] Watches for changes in files, runs corresponding test(s) in Chrome.
gulp test --watch --verbose[1] Same as "watch" with logging enabled.
gulp test --saucelabs[1] Runs test on saucelabs (requires setup).
gulp test --safari[1] Runs tests in Safari.
gulp test --firefox[1] Runs tests in Firefox.
gulp test --files=<test-files-path-glob>[1] Runs specific test files.
gulp serve Serves content in repo root dir over http://localhost:8000/. Examples live in http://localhost:8000/examples/
npm run ava[1] Run node tests for tasks and offline/node code using ava.

[1] On Windows, this command must be run as administrator.

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.

If your pull request contains JS or CSS changes and it does not change the build system, it will be automatically built and tested on Travis. After the travis run completes, the result will be logged to your PR.

If a test flaked on a pull request you can ask a project owner to restart the tests for you. Use this.retries(x) as the last resort.

Manual testing

The below assume you ran gulp in a terminal.

Examples

The content in the examples directory can be reached at: http://localhost:8000/examples/

For each example there are 3 modes:

  • /examples/abc.html points to prod. This file would not reflect your local changes.
  • /examples/abc.max.html points to your local unminified AMP. You want to use this during normal dev.
  • /examples/abc.min.html points to a local minified AMP. This is closer to the prod setup. Only available after running gulp dist --fortesting.

Document proxy

AMP ships with a local proxy for testing production AMP documents with the local JS version.

For any public AMP document like: http://output.jsbin.com/pegizoq/quiet

You can access is with the local JS at

When accessing min urls make sure you run gulp dist with the --fortesting flag so that we do not strip out the localhost code paths. (We do some code elimination to trim down the file size for the file we deploy to production)

If the origin resource is on HTTPS, the URLs are http://localhost:8000/max/s/output.jsbin.com/pegizoq/quiet and http://localhost:8000/min/s/output.jsbin.com/pegizoq/quiet

A4A envelope

AMP ships with a local A4A envelope for testing local and production AMP documents with the local JS version.

A4A can be run either of these two modes:

  1. Friendly iframe mode: http://localhost:8000/a4a/...
  2. 3p iframe mode: http://localhost:8000/a4a-3p/...

The following forms are supported:

When accessing min urls make sure you run gulp dist with the --fortesting flag so that we do not strip out the localhost code paths. (We do some code elimination to trim down the file size for the file we deploy to production)

If the origin resource is on HTTPS, the URLs are http://localhost:8000/a4a[-3p]/max/s/output.jsbin.com/pegizoq/quiet and http://localhost:8000/a4a[-3p]/min/s/output.jsbin.com/pegizoq/quiet

Notice that all documents are assumed to have a "fake" signature. Thus, this functionality is only available in the localDev mode.

Additionally, the following query parameters can be provided:

  • width - the width of the amp-ad (default "300")
  • height - the height of the amp-ad (default "250")

Chrome extension

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

Deploying AMP on Cloud for testing on devices

For deploying and testing local AMP builds on HEROKU , please follow the steps outlined in this document.

Meantime, you can also use our automatic build on Heroku link, which is normally built with latest head on master branch (please allow delay). The first time load is normally slow due to Heroku's free account throttling policy.

To correctly get ads and third party working when testing on hosted services you will need set the AMP_TESTING_HOST environment variable. (On heroku this is done through heroku config:set AMP_TESTING_HOST=my-heroku-subdomain.herokuapp.com)

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
  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.

Code of conduct