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
-
Install NodeJS version >= 6 (which includes npm)
-
Install Yarn version >= 1.2.0 (instructions here, this may require elevated privileges using
sudo
on some platforms) -
Install Gulp by running
yarn global add gulp
(this may require elevated privileges usingsudo
on some platforms) -
Add this line to your hosts file (
/etc/hosts
on Mac or Linux,%SystemRoot%\System32\drivers\etc\hosts
on Windows):127.0.0.1 ads.localhost iframe.localhost
-
Fork the amphtml repository by clicking "Fork" in the Web UI.
-
Create your local repository:
git clone git@github.com:<your username>/amphtml.git
-
Add an alias: Go to the newly created local repository directory and run
git remote add upstream git@github.com:ampproject/amphtml.git
- Create the branch:
git branch --track <branch name> origin/master
- Go to the branch:
git checkout <branch name>
- Make sure you have the latest packages (after you pull):
yarn
- Start the server:
gulp
- Access your server at http://localhost:8000
- Access your sample pages at http://localhost:8000/examples
- Run the tests:
gulp test
- Run the tests in a specified set of files:
gulp test --files=<filename>
- Add the
--watch
flag to anygulp test
command to automatically re-run the tests when a file changes - To run only a certain set of Mocha tests change
describe
todescribe.only
for the tests you want to run; combine this withgulp test --watch
to automatically rerun your test when files are changed (but make sure to run all the tests before sending your change for review)
- Edit files in your favorite editor
- if your code requires a new dependency, run
yarn add --dev --exact [packagename]
, which will automatically updatepackage.json
andyarn.lock
- if you manually edited
package.json
, runyarn install
to install the dependency and generate an updatedyarn.lock
file - Add each file you change:
git add <file>
- Create a commit:
git commit -m "<your commit message>"
- Instead of
add
ing each file individually you can use the-a
flag on the commit instead
git checkout master
git pull upstream master
git checkout <branch name>
git rebase master
- Note that you may need to resolve conflicting changes at this point
- Pull the latest changes as described above
git checkout <branch name>
git push 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)
- If your 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
- If you don't get a new review within 2 business days, feel free to ping the pull request by adding a comment
- Once approved your changes are merged into the amphtml repository by a core committer (you don't do this merge)
- Go to the master branch:
git checkout master
- Delete your local branch:
git branch -D <branch name>
- Delete the GitHub fork branch:
git push origin --delete <branch name>
- Barring any issues releases are cut on Wednesdays, pushed to Dev Channel Thursday, pushed to 1% of AMP pages on Monday and pushed to all pages a few days later on Thursday.
- The amphtml Releases page will list your PR in the first build that contains it.
Pre-release
is the build on the Dev Channel,Latest Release
is the build in production. - Opt-in to using the Dev Channel in a browser by enabling
dev-channel
on 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>
).