Skip to content

Commit b125717

Browse files
radevasis0k0
radeva
authored and
sis0k0
committed
docs(readme): Update readme and add Contributing.md (NativeScript#1170)
- add more description about the repo in the readme - add Get Help section in the readme - move local setup to DevelopmentWorkflow.md - add contributing.md guide - describe the steps to run plugin end-2-end tests with Appium
1 parent 447a3ce commit b125717

File tree

3 files changed

+194
-64
lines changed

3 files changed

+194
-64
lines changed

‎CONTRIBUTING.md

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Contributing to NativeScript Angular
2+
3+
:+1: First of all, thank you for taking the time to contribute! :+1:
4+
5+
Here are some guides on how to do that:
6+
7+
<!-- TOC depthFrom:2 -->
8+
9+
- [Code of Conduct](#code-of-conduct)
10+
- [Reporting Bugs](#reporting-bugs)
11+
- [Requesting Features](#requesting-features)
12+
- [Submitting a PR](#submitting-a-pr)
13+
- [Where to Start](#where-to-start)
14+
15+
<!-- /TOC -->
16+
17+
## Code of Conduct
18+
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).
19+
20+
21+
## Reporting Bugs
22+
23+
1. Always update to the most recent master release; the bug may already be resolved.
24+
2. Search for similar issues in the issues list for this repo; it may already be an identified problem.
25+
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](#pr) section).
26+
27+
## Requesting Features
28+
29+
1. Use Github Issues to submit feature requests.
30+
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.
31+
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.
32+
33+
## Submitting a PR
34+
35+
Before you begin:
36+
* Read and sign the [NativeScript Contribution License Agreement](http://www.nativescript.org/cla).
37+
* Make sure there is an issue for the bug or feature you will be working on.
38+
39+
Following these steps is the best way to get you code included in the project:
40+
41+
1. Fork and clone the nativescript-angular repo:
42+
```bash
43+
git clone https://github.com/<your-git-username>/nativescript-angular.git
44+
# Navigate to the newly cloned directory
45+
cd nativescript-angular
46+
# Add an "upstream" remote pointing to the original repo.
47+
git remote add upstream https://github.com/NativeScript/nativescript-angular.git
48+
```
49+
50+
2. Read our [development workflow guide](DevelopmentWorkflow.md) for local setup:
51+
52+
3. Create a branch for your PR
53+
```bash
54+
git checkout -b <my-fix-branch> master
55+
```
56+
57+
4. The fun part! Make your code changes. Make sure you:
58+
- Follow the [code conventions guide](https://github.com/NativeScript/NativeScript/blob/master/CodingConvention.md).
59+
- Write unit tests for your fix or feature.
60+
61+
5. Before you submit your PR:
62+
- Rebase your changes to the latest master: `git pull --rebase upstream master`.
63+
- Ensure all unit test are green. Check [running unit tests](DevelopmentWorkflow.md#running-the-tests).
64+
- Ensure your changes pass tslint validation. (run `npm run tslint` in the root of the repo).
65+
66+
6. Push your fork. If you have rebased you might have to use force-push your branch:
67+
```
68+
git push origin <my-fix-branch> --force
69+
```
70+
71+
7. [Submit your pull request](https://github.com/NativeScript/nativescript-angular/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.
72+
73+
It's our turn from there on! We will review the PR and discuss changes you might have to make before merging it! Thanks!
74+
75+
76+
## Where to Start
77+
78+
If you want to contribute, but you are not sure where to start - look for [issues labeled `help wanted`](https://github.com/NativeScript/nativescript-angular/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).

‎DevelopmentWorkflow.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Development Workflow
2+
3+
<!-- TOC depthFrom:2 -->
4+
5+
- [Running locally](#running-locally)
6+
- [Prerequisites](#prerequisites)
7+
- [Install dependencies](#install-dependencies)
8+
- [Run the sample application (ng-sample)](#run-the-sample-application-ng-sample)
9+
- [Running the tests](#running-the-tests)
10+
- [Testing locally by running e2e tests](#testing-locally-by-running-e2e-tests)
11+
- [Developer workflow](#developer-workflow)
12+
13+
<!-- /TOC -->
14+
15+
## Running locally
16+
17+
### Prerequisites
18+
19+
Install your native toolchain and NativeScript as described in the docs:
20+
21+
https://docs.nativescript.org/setup/quick-setup
22+
23+
24+
### Install dependencies
25+
26+
```
27+
$ cd nativescript-angular
28+
$ npm install
29+
```
30+
31+
### Run the sample application (ng-sample)
32+
33+
Install NPM packages (use the local copy of `nativescript-angular`):
34+
```
35+
$ cd ng-sample
36+
$ npm install
37+
```
38+
39+
Start the app:
40+
41+
```
42+
$ tns run android
43+
$ tns run ios
44+
```
45+
46+
## Running the tests
47+
48+
Install NPM packages (use the local copy of `nativescript-angular`):
49+
```
50+
$ cd tests
51+
$ npm install
52+
```
53+
54+
Start test run:
55+
56+
```
57+
$ tns test ios
58+
$ tns test android
59+
```
60+
61+
## Testing locally by running e2e tests
62+
63+
NOTE: The steps below describe how to run `renderer` tests, but the same approach can be used to run `router` or any other `e2e` tests.
64+
65+
1. Navigate to `e2e/renderer`
66+
``` bash
67+
cd e2e/renderer
68+
```
69+
70+
2. Install dependencies. This also installs your local copy of the nativescript-angular plugin.
71+
``` bash
72+
npm install
73+
```
74+
3. Make sure to have an emulator set up or connect a physical Android/iOS device.
75+
76+
4. Build the app for Android or iOS
77+
```bash
78+
tns run android/ios
79+
```
80+
81+
5. Install [appium](http://appium.io/) globally.
82+
``` bash
83+
npm install -g appium
84+
```
85+
86+
6. Follow the instructions in the [nativescript-dev-appium](https://github.com/nativescript/nativescript-dev-appium#custom-appium-capabilities) plugin to add an appium capability for your device inside `./e2e/renderer/e2e/config/appium.capabilities.json`.
87+
88+
7. Run the automated tests. The value of the `runType` argument should match the name of the capability that you just added.
89+
``` bash
90+
npm run e2e -- --runType capabilityName
91+
```
92+
93+
## Developer workflow
94+
95+
1. Make changes to the `test`, `ng-sample` projects or in `nativescript-angular` folder.
96+
2. Run the `tests` or `ng-sample` as shown above.

‎README.md

+20-64
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,41 @@
1+
# NativeScript Angular
12
[![Build Status](https://travis-ci.org/NativeScript/nativescript-angular.svg?branch=master)](https://travis-ci.org/NativeScript/nativescript-angular)
23

3-
Integrating NativeScript with Angular.
4+
This repository contains the code for integration of NativeScript with Angular.
45

5-
# Running locally
6+
[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. [Angular](https://angular.io/) is one of the most popular open source JavaScript frameworks for application development. We [worked closely with developers at Google](http://angularjs.blogspot.bg/2015/12/building-mobile-apps-with-angular-2-and.html) to make Angular in NativeScript a reality. The result is a software architecture that allows you to build mobile apps using the same framework—and in some cases the same code—that you use to build Angular web apps, with the performance you’d expect from native code. [Read more about building truly native mobile apps with NativeScript and Angular](https://docs.nativescript.org/tutorial/ng-chapter-0).
67

7-
## Prerequisites
88

9-
Install your native toolchain and NativeScript as described in the docs:
9+
<!-- TOC depthFrom:2 -->
1010

11-
https://docs.nativescript.org/setup/quick-setup
11+
- [Watch the video explaining Angular and NativeScript](#watch-the-video-explaining-angular-and-nativescript)
12+
- [Explore the examples](#explore-the-examples)
13+
- [Contribute](#contribute)
14+
- [Known issues](#known-issues)
15+
- [Get Help](#get-help)
1216

17+
<!-- /TOC -->
1318

14-
## Install dependencies
1519

16-
```
17-
$ cd nativescript-angular
18-
$ npm install
19-
```
20-
21-
## Run the sample application (ng-sample)
22-
23-
Install NPM packages (use the local copy of `nativescript-angular`):
24-
```
25-
$ cd ng-sample
26-
$ npm install
27-
$ npm install ../nativescript-angular
28-
```
29-
30-
Start the app:
31-
32-
```
33-
$ tns run android
34-
$ tns run ios
35-
```
36-
37-
# Running the tests
38-
39-
Install NPM packages (use the local copy of `nativescript-angular`):
40-
```
41-
$ cd tests
42-
$ npm install
43-
$ npm install ../nativescript-angular
44-
```
45-
46-
Start test run:
47-
48-
```
49-
$ tns test ios --emulator
50-
$ tns test android --emulator
51-
```
52-
53-
# Developer workflow:
54-
55-
## Setup:
56-
Use `npm link` to link `nativescript-angular` in `tests` and `ng-sample` projects:
57-
58-
```
59-
cd nativescript-angular
60-
npm link
61-
cd ../ng-sample
62-
npm link nativescript-angular
63-
cd ../tests
64-
npm link nativescript-angular
65-
```
66-
67-
## Work
68-
1. Make changes to the `test`, `ng-sample` projects or in `nativescript-angular` folder.
69-
2. Run the `tests` or `ng-sample` using as shown above.
70-
71-
# Watch the video explaining Angular and NativeScript
20+
## Watch the video explaining Angular and NativeScript
7221
[NativeScript session on AngularConnect conference](https://www.youtube.com/watch?v=4SbiiyRSIwo)
7322

74-
# Explore the examples
23+
## Explore the examples
7524

7625
The `ng-sample` app is meant for testing stuff while developing the renderer code, and isn't the best example out there. You can take a look at these sample apps that use the published builds from npm:
7726

7827
* [Hello world starter](https://github.com/NativeScript/template-hello-world-ng)
7928
* [TodoMVC sample implementation](https://github.com/NativeScript/sample-ng-todomvc)
8029

81-
# Known issues
30+
## Contribute
31+
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/nativescript-angular/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
32+
33+
## Known issues
8234

8335
1. There are certain issues with the Parse5DomAdapter and we'll likely need to provide our own later on:
8436
* Self-closing elements (`<Label text="Name" /><Button text="Save" />`) get parsed wrong (in this case Button gets parsed as a Label child.
37+
38+
## Get Help
39+
Please, use [github issues](https://github.com/NativeScript/nativescript-angular/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).
40+
8541
![](https://ga-beacon.appspot.com/UA-111455-24/nativescript/nativescript-angular?pixel)

0 commit comments

Comments
 (0)