Skip to content

Latest commit

 

History

History
109 lines (77 loc) · 6.48 KB

getting-started-quick.md

File metadata and controls

109 lines (77 loc) · 6.48 KB
Raw

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 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 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 and then git branch -u upstream/master master

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

  • Create and go to the branch: git checkout -b <branch name> master

Build AMP & run a local server

Test AMP

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

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 -d origin <branch name>

See your changes in production

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