Contributing to AMP HTML
The AMP HTML project strongly encourages technical contributions!
We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.
- Reporting issues with AMP
- Contributing code
- Contributing features
- Contributing extended components
- Contributor License Agreement
- Ongoing participation
Reporting issues with AMP
The best bug reports provide a detailed description of the issue (including screenshots if possible), step-by-step instructions for predictably reproducing the issue, and possibly even a working example that demonstrates the issue.
Questions about AMP
Questions about how to use AMP or other general questions about AMP should be asked on Stack Overflow under the AMP HTML tag instead of filing an issue here.
Questions and issues related to Google Search should be asked on Google's AMP forum.
Suggestions and feature requests
The AMP Project is meant to evolve with feedback. The project and its users appreciate your thoughts on ways to improve the design or features.
To make a suggestion or feature request file a GitHub issue describing your idea.
If you are suggesting a feature that you are intending to implement, please see the Contributing features section below for next steps.
The AMP Project accepts and greatly appreciates code contributions!
If you are contributing code to the AMP Project consider joining the AMP Project on GitHub.
Tips for new open source contributors
If you are new to contributing to an open source project, Git/GitHub, etc. welcome! We are glad you're interested in contributing to the AMP Project and we want to help make your open source experience a success.
The Getting Started End-to-End Guide provides step-by-step instructions for everything from creating a GitHub account to getting your code reviewed and merged. Even if you've never contributed to an open source project before you'll soon be building AMP, making improvements and seeing your code live across the web.
The community has created a list of Great First Issues specifically for new contributors to the project. Feel free to find one of the unclaimed Great First Issues that interests you, claim it by adding a comment to it and jump in!
If you're interested in helping out but can't find a Great First Issue that matches your skills/interests, sign up for our Slack and then reach out in the #welcome-contributors channel or send a Direct Message to mrjoro.
If you run into any problems we have plenty of people who are willing to help; see the How to get help section of the Getting Started guide.
How to contribute code
The Getting Started Quick Start Guide has installation steps and instructions for building/testing AMP.
DEVELOPING.md has some more advanced instructions that may be necessary depending on the complexity of the changes you are making.
A few things to note:
- The AMP Project follows the fork & pull model for accepting contributions.
- Familiarize yourself with our Design Principles.
- Include tests when contributing code. There are plenty of tests that you can use as examples.
- A key feature of AMP is performance. All changes will be analyzed for any performance impact; we particularly appreciate changes that make things even faster. Please include any measured performance impact with substantial pull requests.
Follow this process for contributing new features:
- Familiarize yourself with the AMP Design Principles
- Create a new GitHub issue to start discussion of the new feature.
- Before starting on the code get approval for your feature from an OWNER of your feature's area and a core committer. In most cases the people who can give this approval and are most familiar with your feature's area will get involved proactively or someone else in the community will add them. If you are having trouble finding the right people add a comment on the issue or reach out on one of the channels in How to get help.
- Consider bringing the eng design for your feature to our weekly design review.
- Follow the guidelines for Contributing code described above.
Contributing extended components
A key feature of the AMP HTML project is its extensibility - it is meant to support “Extended Components” that provide first-class support for additional rich features.
Because Extended Components may have significant impact on AMP HTML performance, security, and usage, Extended Component contributions will be very carefully analyzed and scrutinized.
In particular we strive to design the overall component set, so that a large number of use cases can be composed from them. Instead of creating a new component it may thus be a better solution to combine existing components to a similar effect.
We have a few additional resources that provide an introduction to contributing extended components:
- "Building an AMP Extension" has a detailed description of how to build an AMP component.
- "Creating your first AMP Component" codelab provides a quick overview of the steps you need to go through to create a component with examples you can modify for your component.
- The "Building a new AMP component" talk at AMP Conf 2017 provides an introduction to contributing AMP components.
For further detail on integrating third party services, fonts, embeds, etc. see our 3p contribution guidelines.
Contributor License Agreement
The AMP Project hosted at GitHub requires all contributors to sign a Contributor License Agreement in order to protect contributors and users in issues of intellectual property.
We recommend signing the CLA before you send a pull request to avoid problems, though this is not absolutely necessary until your code is ready to be merged in.
Make sure that you sign the CLA with the same email address you associate with your commits (likely via the
user.email Git config as described on GitHub's Set up Git page).
- If you are contributing code on your own behalf you can sign the (individual CLA instantly online.
- If you are planning on contributing code on behalf of your company your company will need to agree to a corporate CLA if it has not already done so. Although this is a relatively straightforward process, it requires approval from an authorized signer at your company and a manual verification process, so to ensure you can get your code reviewed and merged quickly please start this process as soon as possible.
- If your company has already agreed to a corporate CLA you can indicate agreement to the CLA by having the appropriate person at your company add your email address added to the Google Group associated with your corporate CLA.
We actively encourage ongoing participation by community members.
Technical issues, designs, etc. are discussed using several different channels:
Weekly status updates
Weekly updates from members of the community are tracked using Weekly Status GitHub issues.
We encourage everyone who is actively contributing to AMP to add a comment to the relevant Weekly Status issue.
Weekly design reviews
The community holds weekly engineering design reviews via video conference. We encourage everyone in the community to participate in these discussions and to bring their designs for new features and significant bug fixes to these reviews.
AMP Project working groups bring together parties with related interests to discuss ideas for how AMP can evolve and to receive updates on new features and changes in AMP that are relevant to the group.