DEVELOPING.md

Development on AMP HTML

How to get started

Before you start developing in AMP, check out these resources:

• CONTRIBUTING.md has details on various ways you can contribute to the AMP Project.
  • If you're developing in AMP, you should read the Contributing code and Contributing features sections.
  • The Ongoing participation section has details on various ways of getting in touch with others in the community including email and Slack.
  • If you are new to open source projects, Git/GitHub, etc., check out the Tips for new open source contributors which includes information on getting help and finding your first bug to work on.
• The Getting Started Quick Start Guide has installation steps and basic instructions for one-time setup, how to build AMP & run a local server and how to test AMP.

Guidelines & Style

Before you start writing code, consult these resources for guidance and guidelines on:

• Design: AMP Design Principles
• JavaScript: Google JavaScript Code Style Guide
• CSS: Writing CSS For AMP Runtime
• Creating new components:
  • Instructions and Guidelines for building an AMP component
  • Learn to create your first component in this codelab
  • Watch this YouTube video to learn about "Building a new AMP component"
• Integrating third-party software, embeds, services: Guidelines

Testing

For most developers, the instructions in the Getting Started Quick Start Guide will be sufficient for building/running/testing during development.

For detailed information on testing, see TESTING.md.

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
  contributing/   - docs for people contributing to the AMP Project
  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.
  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
  third_party/    - third party code used in AMP
  tools/          - code for AMP related tools
  validator/      - AMP Validator runners and tools
  

Supported browsers

In general we support the 2 latest versions of major browsers like Chrome, Firefox, Edge, Safari, Opera, and UC Browser. We support desktop, phone, tablet and the web view version of these respective browsers. For iOS we support the latest 2 major versions which covers about 2 years.

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 IE 11, iOS 8, the Android 4.0 system browser and Chrome 41.

Eng docs

• Life of an AMP *
• AMP Layout system
• Building an AMP Extension

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

Code Reviews

Before any code can be merged into the AMP repository, it has to be reviewed and approved by the owner and a core committer.

• If you are contributing a fix or a new feature to AMP, be sure to follow the tips on preparing your code for review and follow instructions on how to submit a pull request.

• Pull requests in AMP are triaged similar to Issues and within 2 business days of submitting a PR, someone will be assigned as the reviewer. If you have been working with a core committer or someone else already, @mentioning them in the PR description will be helpful.

• After a reviewer is assigned, expect comments on your code within a few days. Feel free to @mention the reviewer if your PR is high priority or if you don't hear back after 2 business days since opening the PR.

• Turnaround time for a PR to be merged is variable and depends on the size and quality of the code. Most PRs go through multiple cycles of review comments. It can take anywhere between a day for simple fixes to weeks for larger features.

• When you have addressed all the review comments from the reviewer, please be sure to @mention them with a "All requested changes are done, please take another look" comment in the PR so they would know PR is ready for the next round.

• If your PR is urgent or not progressing at the pace outlined above, please feel free to ping the #contributing channel on Slack.

Builds and releases

• The AMP buildcop helps ensure that AMP's builds remain green (i.e. everything builds and all of the tests pass). If you run into issues with builds that seem unrelated to your changes see if the issue is present on Travis and let the buildcop know.
• Understanding the AMP release process is useful for understanding when a change in AMP will make it into production and what to do if things go wrong during the rollout of a change.

Code of conduct