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.
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)
shell
```
nvm install --lts
```
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 as origin.

Download your fork to a local repository.

shell

git clone [email protected]:<your username>/amphtml.git

Add an alias called upstream to refer to the main ampproject/amphtml repository. Go to the root directory of the newly created local repository directory and run:
shell
```
git remote add upstream [email protected]:ampproject/amphtml.git
```
Fetch data from the upstream remote:
shell
```
git fetch upstream main
```
Set up your local main branch to track upstream/main instead of origin/main (which will rapidly become outdated).
shell
```
git branch -u upstream/main main
```
Sign in to these services that are used to validate amphtml pull requests.
- CLA Assistant: Mandatory step, used by AMP's contributor license agreement. Sign in here using your GitHub credentials.
- CircleCI: Mandatory step, used to perform continuous integration testing. Sign in here using your GitHub credentials.
- Percy: Optional step, only needed to approve visual diffs introduced by a PR. Sign in here using your GitHub credentials and link it to a Browserstack profile.

Create and go to the branch:

shell

git checkout -b <branch name> main

Run the unit tests: amp unit (doesn't build the runtime)
Run the integration tests: amp integration (builds the runtime)
Run integration tests, but skip building after having done so previously: amp integration --nobuild
Run the tests in a specified set of files: amp [unit|integration] --files=<test-files-path-glob>
Add the --watch flag to amp [unit|integration] to automatically re-run the tests when a file changes
To run only a certain set of Mocha tests, change describe to describe.only for the tests you want to run; combine this with amp [unit|integration] --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 npm install --save-dev [packagename], which automatically updates package.json and package-lock.json
- If it is a build-time dependency, use the --dev flag
- If it is a runtime dependency, add it to build-system/compile/sources.js
If you manually edited package.json, run npm install to install the dependency and generate an updated package-lock.json 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 use git commit -a -m "<your commit message>" instead.

Check out the main branch: git checkout main
Pull the latest changes: git pull
Check out your branch: git checkout <branch name>
Merge the changes to your branch: git merge main

Note: You may need to resolve conflicting changes at this point.

Push the changes:

shell

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.

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 Experimental Channel, Latest Release is the build in production.
Opt in to using the Experimental Channel in a browser by enabling experimental-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>.