Skip to content

Latest commit

 

History

History
153 lines (108 loc) · 6.24 KB

DEVELOPER.md

File metadata and controls

153 lines (108 loc) · 6.24 KB
Raw

Building and Testing ng-toggle

This document describes how to set up your development environment to build and test ng-toggle. It also explains the basic mechanics of using git, node and yarn.

See the contribution guidelines if you'd like to contribute to ng-toggle.

Prerequisite Software

Before you can build and test ng-toggle, you must install and configure the following products on your development machine:

  • Git and/or the GitHub app (for Mac or Windows); GitHub's Guide to Installing Git is a good source of information.

  • Node.js, (version >=8.9.0) which is used to run tests, and generate distributable files. Depending on your system, you can install Node either from source or as a pre-packaged bundle.

  • We use Yarn (version >=1.3.0) to manage dependencies. Please, see installation instructions on their site.

  • We use Chrome to run our tests.

Getting the Sources

Fork and clone the ng-toggle repository:

  1. Login to your GitHub account or create one by following the instructions given here.
  2. Fork the main ng-toggle repository.
  3. Clone your fork of the ng-toggle's ng-toggle repository and define an upstream remote pointing back to the ng-toggle's ng-toggle repository that you forked in the first place.
# Clone your GitHub repository:
git clone [email protected]:<github username>/ng-toggle.git ng-toggle

# Go to the ng-toggle directory:
cd ng-toggle

# Add the main ng-toggle repository as an upstream remote to your repository:
git remote add upstream https://github.com/nth-cloud/ng-toggle.git

Installing Dependencies

Next, install the JavaScript modules needed to build and test ng-toggle:

# Install ng-toggle project dependencies (package.json)
yarn

Project Structure

We use @angular/cli to build both ng-toggle library and demo site. There are two main projects:

  • ng-toggle - the ng-toggle library itself; sources are located in src folder
  • demo - the demo site deployed at https://nth-cloud.github.io/ng-toggle; sources are located in demo/src folder

Useful Commands

The most useful commands are:

yarn demo

Serves the demo site locally in dev mode at http://localhost:9090/. You can optionally add --prod argument to serve demo in production mode or --aot to serve demo in dev mode, but with AOT

yarn build

Builds both library and demo site in production mode. The library will be built in Angular Package format in dist folder. The demo site will be built in demo/dist folder.

yarn tdd

Runs unit tests for the library in watch mode without any additional checks

Note: If you want to only run a single test you can alter the test you wish to run by changing it to fit or describe to fdescribe. This will only run that individual test and make it much easier to debug. xit and xdescribe can also be useful to exclude a test and a group of tests respectively.

yarn test

Checks formatting, linting and runs all tests for the library with coverage

yarn ci

Runs exactly the same suite of actions as the CI server, so you might want to do it before opening a PR

yarn check-format

Checks that your source code is properly formatted without running anything else (see next section)

You can inspect package.json scripts section for a full list of commands available.

Formatting with clang-format

We use clang-format to automatically enforce code style for our TypeScript code. This allows us to focus our code reviews more on the content, and less on style nit-picking. It also lets us encode our style guide in the .clang-format file in the repository, allowing many tools and editors to share our settings.

To check the formatting of your code, run

yarn check-format

Your life will be easier if you include the formatter in your standard workflow. Otherwise, you'll likely forget to check the formatting, and waste time waiting for a build on Travis that fails due to some whitespace difference.

  • Install clang-format with npm install -g clang-format.
  • Use clang-format -i [file name] to format a file (or multiple). Note that clang-format tries to load a clang-format node module close to the sources being formatted, or from the $CWD, and only then uses the globally installed one - so the version used should automatically match the one required by the project. Use clang-format -version in case you get confused.
  • Use yarn check-format to check if your code is clang-format clean. This also gives you a command line to format your code.
  • clang-format also includes a git hook, run git clang-format to format all files you touched.
  • You can run this as a git pre-commit hook to automatically format your delta regions when you commit a change. In the ng-toggle repo, run
    $ echo -e '#!/bin/sh\nexec git clang-format' > .git/hooks/pre-commit
    $ chmod u+x !$
  • WebStorm can run clang-format on the current file.
    1. Under Preferences, open Tools > External Tools.
    2. Plus icon to Create Tool
    3. Fill in the form:
    • Name: clang-format
    • Description: Format
    • Synchronize files after execution: checked
    • Open console: not checked
    • Show in: Editor menu
    • Program: [path to clang-format, try $ echo $(npm config get prefix)/bin/clang-format]
    • Parameters: -i -style=file $FilePath$
    • Working directory: $ProjectFileDir$
  • clang-format integrations are also available for many popular editors (vim, emacs, Sublime Text, etc.).