Skip to content

Latest commit

 

History

History
103 lines (72 loc) · 5.63 KB

getting-started-quick.md

File metadata and controls

103 lines (72 loc) · 5.63 KB

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.

One-time Setup

  • 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 using sudo 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

Branch (do this each time you want a new branch)

  • Create the branch: git branch --track <branch name> origin/master
  • Go to the branch: git checkout <branch name>

Build AMP & run a local server

Test AMP

  • Run the tests: gulp test
  • Run the tests in a specified set of files: gulp test --files=<filename>
  • Add the --watch flag to any gulp test command 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 gulp 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)

Create commits to contain your changes

  • Edit files in your favorite editor
  • if your code requires a new dependency, run yarn add --dev --exact [packagename], which will automatically update package.json and yarn.lock
  • if you manually edited package.json, run yarn install to install the dependency and generate an updated yarn.lock file
  • Add each file you change: git add <file>
  • Create a commit: git commit -m "<your commit message>"
  • Instead of adding each file individually you can use the -a flag on the commit instead

Pull the latest changes

  • 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

Push your branch & create a Pull Request

  • 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)

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 GitHub fork branch: git push origin --delete <branch name>

See your changes in production

  • 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>).