Permalink
Switch branches/tags
Find file Copy path
183 lines (129 sloc) 15.9 KB

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.

If you have questions about using AMP or are encountering problems using AMP on your site please visit our support page for help.

Contents

Reporting issues with AMP

Bugs

If you find a bug in AMP, please file a GitHub issue. Members of the community are regularly monitoring issues and will try to fix open bugs quickly according to our prioritization guidelines.

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.

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 a new feature section below for next steps.

Contributing code

The AMP Project accepts and greatly appreciates code contributions!

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 Good First Issues specifically for new contributors to the project. Feel free to find one of the unclaimed Good 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 Good 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.

🔖 You might have noticed that we use GitHub emojis in our pull requests. To learn what these emojis mean and which ones to use, see our list of emojis .

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:

For further detail on integrating third-party services (e.g., fonts, embeds, etc.), see our 3p contribution guidelines.

How to contribute code

Contributing to AMP involves two phases:

  1. Concept & Design
  2. Coding & Implementation

Contributing a new feature (concept & design phase)

  1. Familiarize yourself with our Design Principles.
  2. Create an Intent to Implement (I2I) GH issue to discuss your new feature. In your I2I, include the following:
    • A high-level description of the feature.
    • A description of the API you plan to create.
    • If you are integrating a third-party service, provide a link to the third-party's site and product.
    • Details on any data collection or tracking that the feature might perform.
    • A prototype or mockup (for example, an image, a GIF, or a link to a demo).
  3. 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. As part of the design review, you might be required to discuss your design in the weekly design review meeting.
  4. Start coding.

Contributing code for a feature (coding & implementation phase)

  1. If you haven't already, consider joining the AMP Project. This is entirely optional but by joining the project you become part of the AMP contributor community, and it allows for the ability to assign issues to you in GitHub.
  2. Perform the one-time setup: Set up your GitHub account, install Node, Yarn, Gulp CLI, fork repo, track repo, etc.
  3. Create a working branch.
  4. Build AMP.
  5. Write code and consult these resources for guidance and guidelines:
  6. Commit your files.
  7. Test your changes: 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.
  8. Put your new component behind an experiment flag.
  9. Pull the latest changes from the AMPHTML repo and resolve any conflicts.
  10. Sign the CLA: This is a one-time task.
  11. Run the pre push check, which is a tool that helps catch any issues before you submit your code. To enable the git pre-push hook, see enable-git-pre-push.sh.
  12. Prepare for your code review:
  13. Push your changes
  14. Send a Pull Request (PR) to review your code. Your PR needs to include:
    • A descriptive title
    • A link to your GitHub Intent To Implement # or Issue #
    • A visual demonstration of your change (e.g., a screenshot, GIF, or links to a published demo (we can link to our Heroku setup which allows developers to publish work-in-progress code to the cloud)
    • @mention the core committer or someone who's already worked with you on the feature
  15. Make sure your PR presubmit passes (no lint and type check errors, tests are passing).
  16. Respond to feedback.
  17. After your PR is approved, it's merged by a core committer. To check on your changes and find out when they get into production, read See your changes in production.
  18. Clean up: After your changes are merged, you can delete your working branch.

Contributor License Agreement

The AMP Project hosted at GitHub requires all contributors to either sign an individual Contributor License Agreement or be covered by a corporate Contributor License Agreement in order to protect contributors and users in issues of intellectual property.

We recommend you handle signing/being covered by a 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 the email you associate with your CLA is 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 that may take a couple of days. To ensure you can get your code reviewed and merged quickly please start this process as soon as possible. The signer of your corporate CLA will associate a Google Group to the corporate CLA, and any email address added to this Google Group will be considered to be covered by this corporate CLA.
    • To be covered by your company's corporate CLA the owner of the Google Group associated with the corporate CLA (someone at your company) will need to add your address to this Google Group.

Ongoing participation

We actively encourage ongoing participation by community members.

Discussion channels

Technical issues, designs, etc. are discussed using several different channels:

  • GitHub issues and pull requests
  • Slack (signup)
    • the #contributing channel is the main channel for you to discuss/ask questions about contributing to the open source project
    • if you're new to contributing to AMP stop by #welcome-contributors to say hi!
    • NOTE: if you have a question about using AMP on your site, use Stack Overflow rather than Slack as Stack Overflow is more actively monitored for these types of questions
    • there are many other Slack channels for more specific topics; after you join our Slack click on the "Channels" header to find other channels you want to participate in
  • the amphtml-discuss Google Group

Status updates

Status updates from members of the community are tracked using approximately bi-weekly Status Update GitHub issues.

We encourage everyone who is actively contributing to AMP to add a comment to the relevant Status Update 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.

Working groups

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.

See also