diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1f7aaa7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing to NativeScript Core Modules Widgets + +:+1: First of all, thank you for taking the time to contribute! :+1: + +Here are some guides on how to do that: + + + +- [Code of Conduct](#code-of-conduct) +- [Reporting Bugs](#reporting-bugs) +- [Requesting Features](#requesting-features) +- [Submitting a PR](#submitting-a-pr) +- [Where to Start](#where-to-start) + + + +## Code of Conduct +Help us keep a healthy and open community. We expect all participants in this project to adhere to the [NativeScript Code Of Conduct](https://github.com/NativeScript/codeofconduct). + + +## Reporting Bugs + +1. Always update to the most recent master release; the bug may already be resolved. +2. Search for similar issues in the issues list for this repo; it may already be an identified problem. +3. If this is a bug or problem that is clear, simple, and is unlikely to require any discussion -- it is OK to open an issue on GitHub with a reproduction of the bug including workflows and screenshots. If possible, submit a Pull Request with a failing test, entire application or module. If you'd rather take matters into your own hands, fix the bug yourself (jump down to the [Submitting a PR](#submitting-a-pr) section). + +## Requesting Features + +1. Use Github Issues to submit feature requests. +2. First, search for a similar request and extend it if applicable. This way it would be easier for the community to track the features. +3. When requesting a new feature, please provide as much detail as possible about why you need the feature in your apps. We prefer that you explain a need rather than explain a technical solution for it. That might trigger a nice conversation on finding the best and broadest technical solution to a specific need. + +## Submitting a PR + +Before you begin: +* Read and sign the [NativeScript Contribution License Agreement](http://www.nativescript.org/cla). +* Make sure there is an issue for the bug or feature you will be working on. + +Following these steps is the best way to get you code included in the project: + +1. Fork and clone the tns-core-modules-widgets repo: +```bash +git clone https://github.com//tns-core-modules-widgets.git +# Navigate to the newly cloned directory +cd tns-core-modules-widgets +# Add an "upstream" remote pointing to the original repo. +git remote add upstream https://github.com/NativeScript/tns-core-modules-widgets.git +``` + +2. Read our [development workflow guide](DevelopmentWorkflow.md) for local setup: + +3. Create a branch for your PR +```bash +git checkout -b master +``` + +4. The fun part! Make your code changes. Make sure you: + - Follow the [code conventions guide](https://github.com/NativeScript/NativeScript/blob/master/CodingConvention.md). + - Write unit tests for your fix or feature. + +5. Before you submit your PR: + - Rebase your changes to the latest master: `git pull --rebase upstream master`. + - Ensure all unit test are green. Check [running unit tests](DevelopmentWorkflow.md#running-the-tests). + - Ensure your changes pass tslint validation. (run `npm run tslint` in the root of the repo). + +6. Push your fork. If you have rebased you might have to use force-push your branch: +``` +git push origin --force +``` + +7. [Submit your pull request](https://github.com/NativeScript/tns-core-modules-widgets/compare). Please, fill in the Pull Request template - it will help us better understand the PR and increase the chances of it getting merged quickly. + +It's our turn from there on! We will review the PR and discuss changes you might have to make before merging it! Thanks! + + +## Where to Start + +If you want to contribute, but you are not sure where to start - look for issues labeled [`help wanted`](https://github.com/NativeScript/tns-core-modules-widgets/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). diff --git a/DevelopmentWorkflow.md b/DevelopmentWorkflow.md new file mode 100644 index 0000000..7a21c8b --- /dev/null +++ b/DevelopmentWorkflow.md @@ -0,0 +1,63 @@ +# Development Workflow + + + +- [Prerequisites](#prerequisites) +- [How to Build the Package](#how-to-build-the-package) +- [How to Build Android](#how-to-build-android) +- [How to Build iOS](#how-to-build-ios) +- [How to Use in an Application](#how-to-use-in-an-application) + + + +## Prerequisites + +Install your native toolchain and NativeScript as described in the docs: https://docs.nativescript.org/setup/quick-setup. In order to open the native Android and iOS project, you need Android Studio and Xcode respectively. + +## How to Build the Package + +On macOS you can execute: + +```shell +$ ./build.sh +``` + +This script builds both Android and iOS, assembles the package at `./dist/package` and packs it as `./dist/tns-core-modules-widgets-*.tgz`. + +## How to Build Android + +On Unix-like operating systems you can execute: + +```shell +$ ./build.android.sh +``` +This script builds only the Android project, assembles the package at `./dist/package` and packs it as `./dist/tns-core-modules-widgets-*.tgz`. The output file is available at `./android/widgets/build/outputs/aar/widgets-release.aar`. + +**NOTE:** To run bash script on Windows you can install [GIT SCM](https://git-for-windows.github.io/) and use Git Bash. + +## How to Build iOS + +On macOS you can execute: + +```shell +$ ./build.ios.sh +``` +This script builds only the Xcode project, assembles the package at `./dist/package` and packs it as `./dist/tns-core-modules-widgets-*.tgz`. The output native iOS framework is available at `./ios/TNSWidgets/build/TNSWidgets.framework`. + +## How to Use in an Application + +You could link the `tns-core-modules-widgets` plugin package to your application through the steps listed below. + +In the `./dist/package` folder execute: + +``` +npm link +``` + +In your application project folder execute: + +``` +npm link tns-core-modules-widgets +``` + +Build the plugin with the above-mentioned commands after each change you would like to test. diff --git a/README.md b/README.md index feb6617..dfc75b6 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,19 @@ +# NativeScript Core Modules Widgets [![Build Status](https://travis-ci.org/NativeScript/tns-core-modules-widgets.svg?branch=master)](https://travis-ci.org/NativeScript/tns-core-modules-widgets) -# Widgets -Contains the source code of the `tns-core-modules-widgets` library. -This library contains native code (Java and Objective-C) used by the NativeScript core modules `tns-core-modules`. +This repository contains the source code of the `tns-core-modules-widgets` library. This library represents native code (Java and Objective-C) used by the NativeScript [`core modules`](https://github.com/NativeScript/NativeScript/tree/master/tns-core-modules). -## How to Build -On Mac in the root folder run: -``` -./build.sh -``` -This will run Android and iOS build and pack `dist/tns-core-modules-widgets-*.tgz`. +[NativeScript](https://www.nativescript.org/) is a framework which enables developers to write truly native mobile applications for Android and iOS using JavaScript and CSS. -## How to Build Android -In the `android` folder run: -``` -gradle build -``` -This will output `android/build/widgets-release.aar`. + -## How to Build iOS -On Mac in the `ios` folder under mac run: -``` -./build.sh -``` -This will output `ios/build/TNSWidgets.framework`. +- [Contribute](#contribute) +- [Get Help](#get-help) + + +## Contribute +We love PRs! Check out the [contributing guidelines](CONTRIBUTING.md) and [development workflow for local setup](DevelopmentWorkflow.md). If you want to contribute, but you are not sure where to start - look for issues labeled [`help wanted`](https://github.com/NativeScript/tns-core-modules-widgets/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). + +## Get Help +Please, use [github issues](https://github.com/NativeScript/tns-core-modules-widgets/issues) strictly for [reporting bugs](CONTRIBUTING.md#reporting-bugs) or [requesting features](CONTRIBUTING.md#requesting-new-features). For general questions and support, check out the [NativeScript community forum](https://discourse.nativescript.org/) or ask our experts in [NativeScript community Slack channel](http://developer.telerik.com/wp-login.php?action=slack-invitation). diff --git a/android/README.md b/android/README.md index f996d0f..5633091 100644 --- a/android/README.md +++ b/android/README.md @@ -1,12 +1,14 @@ -##This is an Android Studio project. +### Android + +This directory contains an Android Studio project. ### How to open? -* File/Open -* Navigate to `tns-core-modules-widgets/android/` -* select and open widgets +* In Android Studio choose: File -> Open +* Navigate to `tns-core-modules-widgets/android/` folder +* On the left side of the screen choose the Project tab and select `widgets` ### How to build? -* Open gradle tab on the right side of the screen -* Navigate to `widgets/Tasks/build/` -* run `build` task -* output will be in `tns-core-modules-widgets/android/dist` +* On the right side of the screen choose the Gradle tab +* Navigate to `android/widgets/Tasks/build/` +* Execute the `assembleRelease` task +* Output will be in `./android/widgets/build/outputs/` diff --git a/build.android.sh b/build.android.sh index 51faa65..6b4390d 100755 --- a/build.android.sh +++ b/build.android.sh @@ -21,7 +21,6 @@ cp android/widgets/build/outputs/aar/widgets-release.aar dist/package/platforms/ echo "Copy NPM artefacts" cp LICENSE dist/package/LICENSE -cp LICENSE.md dist/package/LICENSE.md cp README.md dist/package/README.md cp package.json dist/package/package.json if [ "$1" ] @@ -36,4 +35,3 @@ PACKAGE="$(npm pack)" cd ../.. mv dist/package/$PACKAGE dist/$PACKAGE echo "Output: dist/$PACKAGE" - diff --git a/build.ios.sh b/build.ios.sh index cf0acea..48ee95c 100755 --- a/build.ios.sh +++ b/build.ios.sh @@ -3,7 +3,7 @@ echo "Set exit on simple errors" set -e -echo "Use dumb gradle terminal" +echo "Use dumb terminal" export TERM=dumb echo "Clean dist" @@ -12,7 +12,7 @@ mkdir dist mkdir dist/package mkdir dist/package/platforms -echo "Build ios" +echo "Build iOS" mkdir dist/package/platforms/ios cd ios ./build.sh @@ -21,7 +21,6 @@ cp -r ios/TNSWidgets/build/TNSWidgets.framework dist/package/platforms/ios/TNSWi echo "Copy NPM artefacts" cp LICENSE dist/package/LICENSE -cp LICENSE.md dist/package/LICENSE.md cp README.md dist/package/README.md cp package.json dist/package/package.json if [ "$1" ] diff --git a/build.sh b/build.sh index 4ab652d..e1acb25 100755 --- a/build.sh +++ b/build.sh @@ -19,7 +19,7 @@ cd android cd .. cp android/widgets/build/outputs/aar/widgets-release.aar dist/package/platforms/android/widgets-release.aar -echo "Build ios" +echo "Build iOS" mkdir dist/package/platforms/ios cd ios ./build.sh diff --git a/ios/README.md b/ios/README.md new file mode 100644 index 0000000..06b5c69 --- /dev/null +++ b/ios/README.md @@ -0,0 +1,8 @@ +### iOS + +The `TNSWidgets` directory contains a Xcode project. + +### How to open? +* In Xcode choose: File -> Open +* Navigate to `tns-core-modules-widgets/ios/TNSWidgetes/` folder +* On the left side of the screen choose the Project navigator and select `TNSWidgets`