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 the latest LTS version of Node.js (which includes npm). nvm is a convenient way to do this on Mac and Linux
-
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 [email protected]:<your username>/amphtml.git
-
Add an alias: Go to the newly created local repository directory and run
git remote add upstream [email protected]:ampproject/amphtml.git
and thengit branch -u upstream/master master
- Create and go to the branch:
git checkout -b <branch name> master
- 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 all tests:
gulp test
- Run only the unit tests:
gulp test --unit
(doesn't build the runtime) - Run only the integration tests:
gulp test --integration
(builds the runtime) - Run tests, but skip building after having done so previously:
gulp test --nobuild
- 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
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 -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)
-
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
-
For pushes after the first, just use
git push
-
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, and want to access the results, fill out this form.
-
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 -d origin <branch name>
- 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. Reference our release schedule for more specific details.
- 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>
).