Skip to content

Latest commit

 

History

History
125 lines (90 loc) · 7.73 KB

getting-started-quick.md

File metadata and controls

125 lines (90 loc) · 7.73 KB
Raw

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.

One-time Setup

  1. Create a GitHub account if you don't already have one.

  2. Set up 2 factor auth for your GitHub account.

  3. Install and set up Git; in the "Authenticating" step of that page use SSH instead of HTTPS.

  4. 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

  5. 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.

  6. Download your fork to a local repository.

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

  7. 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:

    git remote add upstream [email protected]:ampproject/amphtml.git

  8. Fetch data from the upstream remote:

    git fetch upstream main

  9. Set up your local main branch to track upstream/main instead of origin/main (which will rapidly become outdated).

    git branch -u upstream/main main

  10. 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.

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

Create and go to the branch:

git checkout -b <branch name> main

Build AMP & run a local server

  1. Make sure you have the latest packages (after you pull): npm install
  2. Start the server: amp
  3. Access your server at http://localhost:8000
  4. Access your sample pages at http://localhost:8000/examples

Test AMP

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

Create commits to contain your changes

  1. Edit files in your favorite editor
  2. Make sure your changes satisfy AMP's code quality and style rules
  3. 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
  4. If you manually edited package.json, run npm install to install the dependency and generate an updated package-lock.json file
  5. Add each file you change: git add <file>
  6. Create a commit: git commit -m "<your commit message>"
  7. To avoid having to run git add on each file, you can use git commit -a -m "<your commit message>" instead.

Pull the latest changes

  1. Check out the main branch: git checkout main

  2. Pull the latest changes: git pull

  3. Check out your branch: git checkout <branch name>

  4. Merge the changes to your branch: git merge main

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

Push your branch & create a Pull Request

  1. Pull the latest changes as described above.

  2. Push the changes:

    git checkout <branch name>
git push -u origin <branch name>

  3. 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")

  4. Make sure you've signed the CLA (using the same email address as your git config indicates)

  5. 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.

  6. 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.

  7. For pushes after the first, just use git push

  8. If you don't get a new review within 2 business days, feel free to ping the pull request by adding a comment.

  9. 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.

  10. Once approved your changes are merged into the amphtml repository by one of your reviewers.

Delete your branch after your changes are merged (optional)

  1. Go to the main branch: git checkout main
  2. Delete your local branch: git branch -D <branch name>
  3. Delete the corresponding 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. 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>.