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). An easy way to do so is with
nvm
. (Mac and Linux: here, Windows: here)nvm install --lts
-
Install the stable version of Yarn. (Mac and Linux: here, Windows: here)
curl -o- -L https://yarnpkg.com/install.sh | bash
An alternative to installing
yarn
is to invoke each Yarn command in this guide withnpx yarn
during local
development. This will automatically use the current stable version ofyarn
. -
If you have a global install of Gulp, uninstall it. (Instructions here. See this article for why.)
yarn global remove gulp
-
Install the Gulp command line tool, which will automatically use the version of
gulp
packaged with the the amphtml repository. (Instructions here)yarn global add gulp-cli
An alternative to installing
gulp-cli
is to invoke each Gulp command in this guide withnpx gulp
during local development. This will also use the version ofgulp
packaged 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
git
asorigin
. -
Download your fork to a local repository.
git clone git@github.com:<your username>/amphtml.git
-
Add an alias called
upstream
to refer to the mainampproject/amphtml
repository. Go to the root directory of the newly created local repository directory and run:git remote add upstream git@github.com:ampproject/amphtml.git
-
Fetch data from the
upstream
remote:git fetch upstream master
-
Set up your local
master
branch to trackupstream/master
instead oforigin/master
(which will rapidly become outdated).git 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 the unit tests:
gulp test --unit
(doesn't build the runtime) - Run the integration tests:
gulp test --integration
(builds the runtime) - Run tests, but skip building after having done so previously:
gulp test [--unit|--integration] --nobuild
- Run the tests in a specified set of files:
gulp test [--unit|--integration] --files=<test-files-path-glob>
- 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
- 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 updatespackage.json
andyarn.lock
- If you manually edited
package.json
, runyarn
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>"
- To avoid having to run
git add
on each file, you can usegit commit -a -m "<your commit message>"
instead.
-
Check out the master branch:
git checkout master
-
Pull the latest changes:
git pull
-
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.
-
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 @username
in 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
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, 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.
- 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>
- 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-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>
.