Skip to content

Latest commit

 

History

History
153 lines (107 loc) · 9.02 KB

DEVELOPING.md

File metadata and controls

153 lines (107 loc) · 9.02 KB
Raw

Development on Subscribe with Google

How to get started

Before you start developing in Subscribe with Google, check out these resources:

  • CONTRIBUTING.md has details on various ways you can contribute to the Subscribe with Google.
    • If you're developing in Subscribe with Google, you should read the Contributing code.

Setup

Now that you have all of the files copied locally you can actually build the code and run a local server to try things out. We use Node.js, the Yarn package manager, Closure Compiler, and the Gulp build system to build swg-js and start up a local server that lets you try out your changes.

  • Install the latest LTS version of Node.js (which includes npm). If you're on Mac or Linux, an easy way to install Node.js is with nvm: 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 with npx yarn during local development. This will automatically use the current stable version of yarn.

  • Closure Compiler is automatically installed by Yarn, but it requires Java 8 which you need to install separately. SWG's version of Closure Compiler won't run with newer versions of Java. Download an installer for Mac, Linux or Windows here.

    • Note: If you are using Mac OS and have multiple versions of Java installed, make sure you are using Java 8 by adding this to ~/.bashrc:
    export JAVA_HOME=`/usr/libexec/java_home -v 1.8`

  • 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 swg-js repository. (instructions here)

    yarn global add gulp-cli

    An alternative to installing gulp-cli is to invoke each Gulp command in this guide with npx gulp during local development. This will also use the version of gulp packaged with the swg-js repository.

  • In your local repository directory (e.g. ~/projects/swg-js), install the packages that SWG uses by running

    yarn

    You should see a progress indicator and some messages scrolling by. You may see some warnings about optional dependencies, which are generally safe to ignore.

Now whenever you're ready to build swg-js and start up your local server, simply go to your local repository directory and run:

gulp

Running the gulp command will compile the code and start up a Node.js server listening on port 8000. Once you see a message like Finished 'default' you can access the local server in your browser at http://localhost:8000

You can browse the http://localhost:8000/examples directory to see some demo pages for various SwG components and combination of components.

Code quality and style

SwG uses Eslint to ensure code quality and Prettier to standardize code style. For easy development, here are two recommendations:

  • Use a code editor with Eslint support to make sure that your code satisfies all of SwG's quality and style rules. Here is a list of editors with Eslint extension support.
  • Set your editor to automatically fix Eslint errors in your code on save.

For example, if you use Visual Studio Code, you can install its Eslint plugin, and enable the eslint.autoFixOnSave setting.

Alternatively, you can manually fix lint errors in your code by running:

gulp lint --local_changes --fix

DNS Aliases

For some local testing we refer to fake local URLs in order to simulate referencing third party URLs. This requires extra setup so your browser will know that these URLs actually point to your local server.

You can do this by adding this line to your hosts file (/etc/hosts on Mac or Linux, %SystemRoot%\System32\drivers\etc\hosts on Windows):

```127.0.0.1               pub.localhost sp.localhost```

Build & Test

Use the following Gulp commands:

Command Description
gulp[1] Runs "watch" and "serve". Use this for standard local dev.
gulp dist[1] Builds production binaries.
gulp lint Validates against Google Closure Linter.
gulp lint --watch Watches for changes in files, Validates against Google Closure Linter.
gulp lint --fix Fixes simple lint warnings/errors automatically.
gulp build[1] Builds the library.
gulp check-links --files foo.md,bar.md Reports dead links in .md files.
gulp clean Removes build output.
gulp watch[1] Watches for changes in files, re-build.
gulp unit Runs unit tests in Chrome.
gulp unit --coverage Runs unit tests in code coverage mode. After running, the report will be available at test/coverage/index.html
gulp e2e Runs end-to-end tests in Chrome.
gulp serve Serves Scenic site on http://localhost:8000/.
gulp serve --quiet Same as serve, with logging silenced.

[1] On Windows, this command must be run as administrator.

Manual testing

For manual testing build Subscribe with Google and start the Node.js server by running gulp.

Repository Layout

  build/          - (generated) intermediate generated files
  build-system/   - build infrastructure
  contributing/   - docs for people contributing to the project
  dist/           - (generated) main JS binaries are created here. This is what
                    gets deployed to CDN.
  docs/           - documentation
  examples/       - example files and corresponding assets
  src/            - source code
  test/           - tests

Deploying for testing

Deploying to App Engine

This repo is configured to be deployable to App Engine. The relevant configuration files are app.yaml and Dockerfile.

To deploy:

  1. Install and init Google Cloud SDK
  2. Create App Engine project if you don't have one yet. Go to the Google Cloud Console and select "Create Project" option. If the project already exists, make sure you have deploy privileges. For more details, see Node.js on App Engine tutorial.
  3. Deploy by executing in command line from the project's root folder: gcloud app deploy --project $PROJECT_ID --stop-previous-version.

Code of conduct