Skip to content

Home

Jump to bottom
Matchy edited this page Nov 25, 2021 · 9 revisions

Art Class App Developer Guide

Table of Contents

Useful links

Prerequisites

This project requires the following components to run properly: Node.js, ionic framework and AWS Amplify CLI. If you would like to run on Android devices, you would also need to install Android Studio.

  1. Node.js

    Install Node.js LTS (Currently 14.18.1). You can directly download Node.js from the official website. However, it is recommended to use nvs to manage the Node.js distribution on your machine.

    To install nvs, simply run the following commands according to the OS of your local machine:

    # Windows
choco install nvs
# Mac, Linux
export NVS_HOME="$HOME/.nvs"
git clone https://github.com/jasongin/nvs "$NVS_HOME"
. "$NVS_HOME/nvs.sh" install

    After installation, restart a new terminal to verify installation by typing

    nvs --version

    And then add Node.js LTS to nvs and activate it

    # Add Node.js LTS to nvs
nvs add lts
# Activate LTS
nvs use lts

    Optionally, you can add Node.js LTS to your PATH to avoid repetitively activate it

    nvs link lts

    Verify the activation of the correction Node.js by the following command

    node --verison

    which should print v14.18.0.

  2. ionic framework

    Install ionic framework globally through npm (yarn or pnpm not recommended)

    npm install -g @ionic/cli

    Verify the installation by the following command

    ionic --version

  3. Amazon Amplify

    Install amplify cli globally through npm (yarn or pnpm not recommended).

    npm install -g @aws-amplify/cli

    Follow the instructions in Amplify CLI documentation if it is your first time installing

  4. Android Studio (Android SDK)

    Install Android Studio. It has already included the Android SDK.

    Our application targets API 29 or above.

Build and run the project

Prepare the project

Clone the repo and navigate to the root direcotry of this repo.

git clone https://github.com/cloudtrack/snu_class_2021_art.git
cd snu_class_2021_art

Run npm install to install other not globally required dependencies.

npm install

Set up local amplify backend environment.

amplify pull

Since this is an Android application, add android as a target platform to ionic capacitor

ionic cap add android

Simply run the following command to build to Android platform.

ionic cap build android

Run in browser

It's fast to boot and will give you the chance to look at the console log through the debug mode in your browser.

ionic serve

Run in Android Studio

Open the directory android in Android Studio and click run to see the application running on an emulator. It will allow you to test some native features on Android.

Run in Android using ionic capacitor with livereload

The capacitor plugin provided by ionic framework allows you to preview your app on an Android device or an Android virtual device. It requires adb installed since it detects the devices available using adb.

If adb is not installed no your machine (you should have if you followed all the instructions above though), go to the official site to get the platform tool. Alternatively, you can install through choco on Windows by the following command:

choco install adb

Make sure that there are devices available to test on using adb devices

$ adb devices
List of devices attached
<your-device-id>        device

You can use the following command to run and debug the app in a live-reloading manner.

ionic capacitor run android --livereload --external
# or if you are lazy
ionic cap run android -l --external

Project management conventions

Branch management

  1. DO NOT try to commit on main branch directly -- It is not possible anyway.
  2. Create a new branch based on develop branch -- all the newest changes happen on this branch. We also reconcile possible conflicts between branches on this branch
  3. Open a new branch for every ticket in Jira.

Commit conventions

- This is subject to change. I want to try conventional commits

There are two popular ways of writing a commit message: Tim Pope style (This is also recommended in the official guideline of Git, Pro Git), and the Conventional Commits style. The latter one is preferred in many large open-source projects since it dovetails SemVer. Here we adopt the Tim Pope style, for it's succinctness.

Here are the 7 rules for writing a good Tim Pope style commit message:

  1. Limit the subject line to 50 characters.
  2. Capitalize only the first letter in the subject line.
  3. Don't put a period at the end of the subject line.
  4. Put a blank line between the subject line and the body.
  5. Wrap the body at 72 characters.
  6. Use the imperative mood, but not past tense.
  7. Describe what was done and why, but not how.
Clone this wiki locally