Skip to content

Latest commit

 

History

History
142 lines (107 loc) · 5.62 KB

CONTRIBUTING.md

File metadata and controls

142 lines (107 loc) · 5.62 KB
Raw

Contributing

To get started, clone the repo, run npm i, and then npm run src:build (or npm run src:watch). We use TypeScript, so code must be compiled before it runs.

Generating

You can generate the starters by running:

npm run starters:build

You can build a single starter by specifying the path:

npm run starters:build -- angular/official/tabs
  • Starters are generated by overlaying starter files (located in <type>/official/<name>/ or <type>/community/<scope>/<name>/) onto base files (located in <type>/base/) into the build/ directory.
  • Unless the --current flag is passed to the build command, base files are checked out from which ever revision the starter requires (called the starter's baseref).
  • The baseref is defined in the starter's manifest file, which is a special file that invokes additional operations on the generated starter files.

Testing

You can test starters by running:

npm run starters:test

You can test a single starter by specifying the starter ID (also the starter's directory name within the build/ directory):

npm run starters:test -- angular-official-tabs
  • Starters must be generated before they can be tested. The test command works with starters generated in the build/ directory.
  • To test a starter, first the dependencies are installed (npm install), and then the scripts.test key in the starter's manifest file is executed. This way, each starter can define how it must be tested.

Manifest Files

The starter manifest file (named ionic.starter.json) is a required JSON file at the root of the starter. The build process reads the manifest and takes actions based upon what's defined in the file.

Key Description
name The human-readable name.
baseref The latest git ref (branch or sha) at which the starter is compatible with the base files (located in <type>/base/).
welcome (optional) A custom message to be displayed when the user runs ionic start on the starter. See Starter Welcome.
gitignore (optional) During build, the defined array of strings will be added to the bottom of the project's .gitignore file.
packageJson (optional) During build, the defined keys will be recursively merged into the generated package.json.
tsconfigJson (optional) During build, the defined keys will be recursively merged into the generated tsconfig.json.
tarignore (optional) During deploy, the defined array of strings will be interpreted as globs to ignore files to include in the tar file when deployed.
scripts (optional) An object of scripts that run during build or deploy.
scripts.test (optional) During test, after dependencies are installed, the defined script will be executed to test the starter.

Community Starters

To submit your own starter,

  1. Fork this repo.

  2. Fork or copy the Example Starter.

  3. Add a git submodule for your starter at <type>/community/<your github name>/<github repo name>. For example:

    git submodule add https://github.com/ionic-team/starter-example.git ionic-angular/community/ionic-team/example

  4. Build your starter. For example:

    npm run starters:build -- ionic-angular/community/ionic-team/example

  5. Copy the generated starter into a different directory and test it!

To update your starter,

  1. Push changes to your starter repo freely.
  2. Run git pull in your starters fork directory (ionic-angular/community/ionic-team/example for example).
  3. Commit the changes to your fork and create a PR.

Tips:

  • When you cd into a git submodule directory (i.e. ionic-angular/community/ionic-team/example), git commands operate on the submodule as its own repository.
  • Inside a submodule folder, git remote add local /path/to/starter/at/local will add a new git remote which you can use to pull local changes in. Make commits in your local starter repo, then git pull local.
  • New commits in a submodule must also be saved in the base repository for PRs.
  • Don't include a .gitignore file. If you need to ignore some files in your starter repo, you can use the private gitignore file located at .git/info/exclude. If you need to add entries, you can use the gitignore key in your manifest file.

Starter Welcome

For a custom message to be displayed for your starter during ionic start, you can set the welcome key of your starter manifest file to a string. For terminal colors and other formatting, you can create a quick script to generate the message, JSON-encode it, and copy it into your manifest file. See this example script for the Super Starter.

Deploying

During the deploy process, the build/ directory is read and an archive of each generated starter is created and gzipped and uploaded to an S3 bucket. The S3 bucket has a CloudFront distribution for close-proximity downloads. The distribution ID is E1XZ2T0DZXJ521 and can be found at this URL.

Starters are deployed automatically when new commits are pushed to the master branch. To deploy manually, run:

npm run starters:deploy

You can use npm run starters:deploy -- --dry to test the tar process.

By default, starters are deployed to the testing "tag" (latest is production). You can install tagged starters by specifying the --tag=<tag> option to ionic start).