Skip to content

Latest commit

 

History

History
109 lines (81 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

109 lines (81 loc) · 4.15 KB
Raw

Contributing

To get started, clone the repo, run npm i, and then npm run tsc (or npm run tsc -- -w). We use TypeScript, so code must be compiled before it runs.

Generating

You can generate the starters by running:

npm run build

You can build a single starter by specifying the path:

npm run build -- ionic-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.

Then, the starter manifest file is read, invoking additional operations on the generated starter files.

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.
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.
gitignore (optional) During build, the defined array of strings will be added to the bottom of the project's .gitignore file.

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 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 deploy