Getting Started: Quick Start
About this guide
This Quick Start guide is the TL;DR version of the longer end-to-end guide for people who don't want/need a longer explanation.
Create a GitHub account if you don't already have one.
Set up 2 factor auth for your GitHub account.
Install and set up Git; in the "Authenticating" step of that page use SSH instead of HTTPS.
nvm install --lts
curl -o- -L https://yarnpkg.com/install.sh | bash
An alternative to installing
yarnis to invoke each Yarn command in this guide with
npx yarnduring local
development. This will automatically use the current stable version of
yarn global remove gulp
yarn global add gulp-cli
An alternative to installing
gulp-cliis to invoke each Gulp command in this guide with
npx gulpduring local development. This will also use the version of
gulppackaged with the amphtml repository.
Create your own fork of the amphtml repository by clicking "Fork" in the Web UI. During local development, this will be referred to by
Download your fork to a local repository.
git clone firstname.lastname@example.org:<your username>/amphtml.git
Add an alias called
upstreamto refer to the main
ampproject/amphtmlrepository. Go to the root directory of the newly created local repository directory and run:
git remote add upstream email@example.com:ampproject/amphtml.git
Fetch data from the
git fetch upstream master
Set up your local
masterbranch to track
origin/master(which will rapidly become outdated).
git branch -u upstream/master master
Branch (do this each time you want a new branch)
Create and go to the branch:
git checkout -b <branch name> master
Build AMP & run a local server
- Make sure you have the latest packages (after you pull):
- Start the server:
- Access your server at http://localhost:8000
- Access your sample pages at http://localhost:8000/examples
- Run the unit tests:
gulp unit(doesn't build the runtime)
- Run the integration tests:
gulp integration(builds the runtime)
- Run integration tests, but skip building after having done so previously:
gulp integration --nobuild
- Run the tests in a specified set of files:
gulp [unit|integration] --files=<test-files-path-glob>
- Add the
gulp [unit|integration]to automatically re-run the tests when a file changes
- To run only a certain set of Mocha tests, change
describe.onlyfor the tests you want to run; combine this with
gulp [unit|integration] --watchto automatically rerun your test when files are changed (but make sure to run all the tests before sending your change for review)
Create commits to contain your changes
- Edit files in your favorite editor
- Make sure your changes satisfy AMP's code quality and style rules
- If your code requires a new dependency, run
yarn add --dev --exact [packagename], which automatically updates
- If you manually edited
yarnto install the dependency and generate an updated
- Add each file you change:
git add <file>
- Create a commit:
git commit -m "<your commit message>"
- To avoid having to run
git addon each file, you can use
git commit -a -m "<your commit message>"instead.
Pull the latest changes
Check out the master branch:
git checkout master
Pull the latest changes:
Check out your branch:
git checkout <branch name>
Merge the changes to your branch:
git merge master
Note: You may need to resolve conflicting changes at this point.
Push your branch & create a Pull Request
Pull the latest changes as described above.
Push the changes:
git checkout <branch name> git push -u origin <branch name>
Go to https://github.com/ampproject/amphtml and in the banner indicating you've recently pushed a branch, click the "Compare & pull request" (if this banner does not appear, go to your fork at
https://github.com/<your username>/amphtml, choose your branch from the "Branch" dropdown and click "New pull request")
Make sure you've signed the CLA (using the same email address as your git config indicates)
Find people to review your code and add them as a reviewer on the PR (if you can) or cc them (by adding
/cc @usernamein the PR description/comment). If your run into any issues finding the reviewers or have any other questions, ping the #contributing channel on Slack.
If a reviewer requests changes make them locally and then repeat the steps in this section to push the changes to your branch back up to GitHub again.
For pushes after the first, just use
If you don't get a new review within 2 business days, feel free to ping the pull request by adding a comment.
If you see visual diffs reported by Percy, click through the check on GitHub to access the results. Differences that are expected can be approved by one of your reviewers.
Once approved your changes are merged into the amphtml repository by one of your reviewers.
Delete your branch after your changes are merged (optional)
- Go to the master branch:
git checkout master
- Delete your local branch:
git branch -D <branch name>
- Delete the corresponding GitHub fork branch:
git push -d origin <branch name>
See your changes in production
- If your change affected internal documentation, tests, the build process, etc. you can generally see your changes right after they're merged.
- If your change was to the code that runs on AMP pages across the web, you'll have to wait for the change to be included in a production release. Generally, it takes about 1-2 weeks for a change to be live for all users. See the release schedule for more specific details.
- The amphtml Releases page will list your PR in the first build that contains it.
Pre-releaseis the build on the Dev Channel,
Latest Releaseis the build in production.
- Opt in to using the Dev Channel in a browser by enabling
dev-channelon the AMP Experiments page.
- Find the AMP version being used on a page in the developer console, i.e.
Powered by AMP ⚡ HTML – Version <build number>.