From 4d671b27262271bd431bbb4062d06377d5c0abd9 Mon Sep 17 00:00:00 2001 From: steffi Date: Wed, 9 Jun 2021 13:14:06 +0200 Subject: [PATCH] LUN-50: Create Readme --- README.md | 59 +++++++++ docs/conventions.md | 65 +++++++++ docs/debugging.md | 31 +++++ docs/setup-windows-android-emulator.md | 177 +++++++++++++++++++++++++ docs/vscode.md | 120 +++++++++++++++++ 5 files changed, 452 insertions(+) create mode 100644 docs/conventions.md create mode 100644 docs/debugging.md create mode 100644 docs/setup-windows-android-emulator.md create mode 100644 docs/vscode.md diff --git a/README.md b/README.md index a18ab697b..243f029b8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,62 @@ # Lunes App Android and iOS React native Apps for [Lunes](https://lunes.app) + +If your are interested in contributing write an e-mail to [Steffi](mailto:metzger@integreat-app.de) for development issues or to [Daniel](mailto:info@lunes.app) for no-technical stuff. + +## Contents + +- [Getting Started](#getting-started) + - [Prerequisites](#prerequisites) + - [Project setup](#project-setup) +- [Conventions](#contributing) +- [Project Structure](#project-structure) +- [Further Reading](#further-reading) + +## Getting Started + +### Prerequisites + +- Rate our Lunes app in the [PlayStore](https://play.google.com/store/apps/details?id=app.lunes) + and the [Apple App Store](https://apps.apple.com/de/app/lunes/id1562834995). +- Install [nodejs](https://nodejs.org/). +- Install [yarn](https://yarnpkg.com/). + +### Project setup + +We suggest **[IntelliJ](https://www.jetbrains.com/idea/)** as IDE on Linux or Mac. +If you are using a different IDE like Visual Studio Code, follow the steps [here](./docs/vscode.md). +If you want to develop on Windows, follow the steps [here](./docs/setup-windows-android-emulator.md). + +- Import this project (VCS > Get from Version Control) and open it. +- Run `yarn` in the terminal to install all dependencies. +- Take a look at the [available scripts](package.json). + + +#### Android + +- Install the Android SDK by using the [Android Support plugin](https://plugins.jetbrains.com/plugin/1792-android-support) in IntelliJ. +- Install the latest stable SDK Platform and Android SDK Tools in the SDK Manager (Settings > Appearance & Behaviour > System Settings > Android SDK) +- \[optional\]: If you want to develop using an emulator, also install the Android Emulator in the Android SDK settings +- run `yarn start` and `yarn android` + +#### iOS + +- Own a Mac or another Apple device. +- Install [XCode](https://developer.apple.com/xcode/). + +_Note: In order to work with the project in XCode, always open `ios/Lunes.xcworkspace`._ + +#### Additional Configuration + +- [optional] Install the following plugins: + - [Styled Components](https://plugins.jetbrains.com/plugin/9997-styled-components--styled-jsx/) + - [Ruby](https://plugins.jetbrains.com/plugin/1293-ruby) (if working with Fastlane) + +## Conventions + +Our [conventions](docs/conventions.md) can be found here + +## Further Reading + +Documentation on [CI/CD](docs/cicd.md) and more can be found in `/docs`. diff --git a/docs/conventions.md b/docs/conventions.md new file mode 100644 index 000000000..dd58d5114 --- /dev/null +++ b/docs/conventions.md @@ -0,0 +1,65 @@ +# Conventions + +## Naming + +We follow the [airbnb style](https://github.com/airbnb/javascript/tree/master/react) for naming. + +## Code style + +We use [prettier](https://prettier.io) to format code. Run `yarn prettier --check .` to show formatting problems or `yarn prettier --write .` to fix them. +We use [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint) for TypeScript linting. Run `yarn lint` to show linting problems. + +## Folder structure + +Tests should always be positioned in a `__tests__` directory on the same level as the file which is tested. + +``` +├── __tests__ +│ └── Caption.spec.js +└── Caption.js +``` + +## Git commit messages and Pull request names + +See [this guide](https://github.com/erlang/otp/wiki/Writing-good-commit-messages) for a general reference on how to write +good commit messages. +Commit messages should have the following schema: +**`: Your commit message`**, e.g. `LUN-612: Add commit message documentation` + +The same applies for PR names. Branch names should also start with ``-Prefix + +## Pull requests + +To merge a pull request, it has to match our Definition of Done. It includes among others: + +- All checks (linting, unit and e2e tests, ...) have to pass. +- No changes are requested. +- Two approvals are needed. +- New and changed functionality should be tested sufficiently, both manual and by writing unit tests. + +**Creating a pull request from a fork prevents checks from the CI. It is a good way to make contact though.** + + +## Versioning + +Versions consist of a version name and a version code. + +### Version name + +The following [schema](https://calver.org/) ![versioning](https://img.shields.io/badge/calver-YYYY.MM.PATCH-22bfda.svg) is used for versioning. +`PATCH` is a counter for the number of releases in the corresponding month starting with 0. + +Examples: + +- First versions of 2020: `2020.1.0`, `2020.1.1`, `2020.1.2`. +- First version of February 2020: `2020.2.0`. + +### Version code + +An additional consecutive version code is used for unique identification in the app stores. +The version code is incremented for every build uploaded to the stores. +The first version code was `100000`. + +### Release notes + +tbd. diff --git a/docs/debugging.md b/docs/debugging.md new file mode 100644 index 000000000..212cb80f2 --- /dev/null +++ b/docs/debugging.md @@ -0,0 +1,31 @@ +# Debugging + +## Flipper + +For debugging [flipper](https://fbflipper.com/) is recommended. +It allows debugging of logs, network requests, views and redux actions. + +### Setup + +- Download and install [flipper](https://fbflipper.com/) +- Run flipper +- Install and run the app which should be debugged +- \[optional\]: Install `redux-debugger` plugin in flipper: + `Manage plugins > Install plugins > redux-debugger > Install` +- \[optional\]: Enable plugins for installation + +#### iOS + +On iOS the [iOS Development Bridge (idb)](https://github.com/facebook/idb#quick-start) has to be installed additionally: + +- `brew tap facebook/fb` +- `brew install idb-companion` +- `pip3 install fb-idb` + +## Intellij + +- Start Android emulator +- in Intellij click start packager in debug mode +- a browser debug windows should open +- click `STRG + M` in the emulator and click `Start debugging` +- set breakpoints in Intellij and start debugging \ No newline at end of file diff --git a/docs/setup-windows-android-emulator.md b/docs/setup-windows-android-emulator.md new file mode 100644 index 000000000..96e12f020 --- /dev/null +++ b/docs/setup-windows-android-emulator.md @@ -0,0 +1,177 @@ +# Android Emulator without Android SDK in Windows + +- [Install Java](#install-java) +- [Install HAXM](#install-haxm) +- [Download cmdline-tools](#download-cmdline-tools) +- [TL;DR - Quickinstall](#tldr---quickinstall) +- [Download android platform tools](#download-android-platform-tools) +- [Download Image and Emulator](#download-image-and-emulator) +- [Final Folder Structure](#final-folder-structure) +- [Set Paths](#set-paths) +- [Create the Android Virtual Device (avd)](#create-the-android-virtual-device-avd) +- [Start the emulator](#start-the-emulator) +- [Using the emulator with WSL2 (untested)](#using-the-emulator-with-wsl2-untested) + +## Install [Java](https://www.java.com/de/) + +``` +choco install jdk8 +``` + +(This should also set the corresponding paths, e.g. `JAVA_HOME C:\Program Files\Java\jdk1.8.0_211` and `PATH C:\Program Files\Java\jdk1.8.0_211\bin`) + +_Installation was only tested with this Java version, different versions may not work_ + +## Install HAXM + +Install HAXM hardware accelerator for the emulator (recommended for powerful PCs) +https://github.com/intel/haxm/releases + +## Download cmdline-tools + +This installs the sdkmanager and the avdmanager. +We need the sdkmanager for downloading the emulator, more info about the tool: +https://developer.android.com/studio/command-line/sdkmanager + +Download Android Command Line Tools from +https://developer.android.com/studio/#cmdline-tools + +Create a new folder for the Sdk (ANDROID_SDK_ROOT), e.g. `C:\Android\Sdk` + +Extract the cmdline-tools and move the content to +`C:\Android\Sdk\cmdline-tools\tools\` +so it contains `\bin` and `\lib` +(This is folder structure important but undocumented, more info [here](https://stackoverflow.com/questions/60440509/android-command-line-tools-sdkmanager-always-shows-warning-could-not-create-se)) + +Open a PowerShell Window and go to + +``` +cd C:\Android\Sdk\cmdline-tools\tools\bin +``` + +to use the sdkmanager and the avdmanager for the next steps + +## TL;DR - Quickinstall + +Set Paths: [Set Paths](#set-paths) + +Run + +``` +sdkmanager --install "system-images;android-29;default;x86" "platform-tools" "platforms;android-29" +echo no | avdmanager create avd --name "android-29_default_x86" --package "system-images;android-29;default;x86" +``` + +Start "yarn android" in src folder + +Enjoy. + +## Download android platform tools + +Download the platform tools including adb and fastboot: + +``` +./sdkmanager.bat "platform-tools" +``` + +This creates a new folder in ANDROID_SDK_ROOT: +`C:\Android\Sdk\platform-tools` + +## Download Image and Emulator + +List the Android System Images available: + +``` +./sdkmanager.bat --list | findstr system-images +``` + +Download the most recent Image and the corresponding platform tools (here android-29). +It also automatically downloads the Emulator. +Do not download an image with "google_api" instead of "default", these contain the Google PlayStore and need a verification + +``` +./sdkmanager.bat --install "system-images;android-29;default;x86" +``` + +as well as the corresponding platform + +``` +sdkmanager "platforms;android-29" +``` + +This downloads the image and the emulator and creates following folder structure in ANDROID_SDK_ROOT: + +## Final Folder Structure + +Your folder inside your ANDROID_SDK_ROOT (here "C:\Android\Sdk") should now look like this + +- **cmdline-tools** _(sdkmanager and avdmanager)_ +- **emulator** +- licenses +- patcher +- **platforms** +- **platform-tools** +- **system-images** + +You now also have a new subfolder in your user folder named ".android" + +## Set Paths + +To use the emulator you need to add the following paths to windows. You should also add the path of sdkmanager and avdmanager to use it from everywhere without changing into the directory. + +Go to "environment variables" (search for env in windows search bar) +In the "System Variables" Section: + +Add the path to the sdk root as new variable: + +``` +ANDROID_SDK_ROOT C:\Android\Sdk +``` + +Add the path to the sdkmanager and the emulator to the existing `PATH` variable: + +``` +C:\Android\Sdk\cmdline-tools\tools\bin +C:\Android\Sdk\emulator +C:\Android\Sdk\platform-tools +``` + +Close and reopen your powershell to have the new paths set. + +## Create the Android Virtual Device (avd) + +We need the avdmanager for creating the Virtual Device from the image we downloaded with the sdkmanager. +More info about the tool: https://developer.android.com/studio/command-line/avdmanager + +Use your downloaded image to create the virtual device (here: "`system-images;android-29;default;x86`"). + +``` +avdmanager --verbose create avd --name "android-29_default_x86" --package "system-images;android-29;default;x86" +``` + +We do not need a special hardware profile, so answer "Do you wish to create a custom hardware profile?" with "no" + +This creates a new subfolder in your user folder with the given name: +`\.android\avd\android-29_default_x86` + +The settings of the Device can be changed settings are in +\.android\avd\android-29_default_x86.avd/config.ini. +To use the keyboard of your PC set + +``` +hw.keyboard=yes +``` + +## Start the emulator + +Start the Virtual Device with + +``` +emulator -avd android-29_default_x86 +``` + +Using "yarn android" in the src folder will find and start the emulator automatically + +## Using the emulator with WSL2 (untested) + +https://medium.com/@pellea/using-the-android-emulator-on-windows-10-with-wsl2-39c2bae30c49 diff --git a/docs/vscode.md b/docs/vscode.md new file mode 100644 index 000000000..d9c02bc96 --- /dev/null +++ b/docs/vscode.md @@ -0,0 +1,120 @@ +# Visual Studio Code Installation + +- [Installation](#installation) +- [Settings](#settings) + - [Optional settings](#optional-settings) +- [Required Extensions](#required-extensions) + - [Eslint Code Formatter](#eslint-code-formatter) +- [Recommended Extensions](#recommended-extensions) + - [Git History](#git-history) + - [... Save your ass](#-save-your-ass) + - [Remote WSL](#remote-wsl) + - [.md-Files](#md-files) + +## Installation + +Download and Install [Visual Studio Code](https://code.visualstudio.com/) or use [Chocolatey](https://chocolatey.org/): + +https://code.visualstudio.com/Download +https://code.visualstudio.com/docs/setup/linux +or + +``` +choco install vscode +``` + +## Settings + +Adjust the following settings corresponding to your preferences: + +``` +File > Preferences > Keyboard Shortcuts +# or install a known ones (e.g. IntelliJ) +File > Preferences > Keymaps +``` + +### Optional settings + +``` +File > Preferences > Settings (Ctrl+,) +``` + +``` +// Do not close file when opening another one +"workbench.editor.enablePreviewFromQuickOpen": false, +"workbench.editor.enablePreview": false, + +// Do not show mini code preview on the right side +"editor.minimap.enabled": false, + +// Do not automatically commmit unstaged files +"git.enableSmartCommit": false, + +// Privacy +"telemetry.enableCrashReporter": false, +"telemetry.enableTelemetry": false, +"update.enableWindowsBackgroundUpdates": false +``` + +## Required Extensions + +The following extensions (or any alternatives) should be installed. + +### Eslint Code Formatter + +``` +code --install-extension dbaeumer.vscode-eslint +code --install-extension esbenp.prettier-vscode +``` + +Activate vs-code-prettier as default formatter. VSCode should ask you, otherwise set it manually: + +``` +"[javascript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" +} +``` + +Until now Lunes uses an external repo for the eslint configuration. After Checking out the repo allow eslint to use the npm module in node_modules/eslint. +The eslint extension button is in the bottom right corner of the IDE + +## Recommended Extensions + +### Git History + +(Alternative: Git Lens) + +``` +code --install-extension donjayamanne.githistory +``` + +### ... Save your ass + +(Changes History) + +``` +code --install-extension xyz.local-history +``` + +Set path in settings: + +``` +"local-history.path": "", +``` + +### Remote WSL + +Use Visual Studio Code in Windows as GUI for code running in WSL +https://code.visualstudio.com/docs/remote/wsl + +``` +code --install-extension ms-vscode-remote.remote-wsl +``` + +### .md-Files + +use button in top right corner see the formatted markup + +``` +code --install-extension yzhang.markdown-all-in-one +```