Skip to content
This repository has been archived by the owner on Jan 9, 2023. It is now read-only.

Improvements done to CONTRIBUTING.md #787

Merged
merged 1 commit into from Nov 8, 2016
Merged

Improvements done to CONTRIBUTING.md #787

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 26 additions & 28 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,55 +36,53 @@ This guide assumes a level of knowledge on how to use GitHub issues and pull req

## Start Coding

This section is designed to help developers start coding in the project and understanding the basic concepts and components used.
This section is designed to help developers start coding in the project and understand the basic concepts and components used.

### Ember

To understand the project you'll have to understand Ember, and it is advisable that you'll follow the tutorial: [Create your own app](https://guides.emberjs.com/v2.9.0/tutorial/ember-cli/) to get an understanding of how ember works and the basic folder structure.

To read how Ember works in the following link: http://emberjs.com.
To understand the project you'll have to understand [Ember](http://emberjs.com), and it is advisable that you'll follow the tutorial: [Create your own app](https://guides.emberjs.com/v2.9.0/tutorial/ember-cli/) to get an understanding of how Ember works and the basic folder structure. You can find more Ember guides [here](https://guides.emberjs.com/v2.9.0/).

### ES6

Since the project is based on Ember, it uses ES6 standard for its client side code.
Since the project is based on Ember, it uses the ES6 standard for its client side code.

### Folder structure

The basic folder structure in **Ember** has the following folders and files
The basic folder structure in Ember has the following folders and files:

| Folder Name | Purpose |
| ----------- | ------- |
| app/router.js | Defines routes and sub-routes in the application
| app/index.html | The basic index html of the system (this file should almost never be changed)
| app/router.js | Defines routes and sub-routes in the application.
| app/index.html | The basic index html of the system (this file should almost never be changed).
| public/ | This directory contains assets such as images and fonts.
| vendor/ | This directory is where front-end dependencies (such as JavaScript or CSS) that are not managed by Bower go.
| dist/ | This folder is auto-generated by ember to contain all the project's compiled files and dependencies so that this folder can be copied as a stand-alone unit to be deployed on a server.
| tmp | Ember CLI temporary files live here.
| ember-cli-build.js | This file is an instruction on how to build the application
| ember-cli-build.js | This file is an instruction on how to build the application.

In addition, these are description of some extra folder and files in use in this project:
In addition, these are descriptions of some extra folders and files in use in this project:

| Folder Name | Purpose |
| ----------- | ------- |
| server/ | This folder contains the basic definition for the application's backend
| server/ | This folder contains the basic definition for the application's backend.
| server/config.js | Basic configuration for the system, like CouchDB config, authentication etc.


### Pod directories

This project uses a folder structure called [Pods](http://cball.me/organize-your-ember-app-with-pods/) the is better suited for a large scale ember application.
This project uses a folder structure called [Pods](http://cball.me/organize-your-ember-app-with-pods/) that is better suited for a large scale Ember application.

The Basic folder structure for Ember puts controllers, route and template in three different directories. The Pods approach organizes the folders in correlation to the application routes and keeps all three files in the same folder for each view.
The basic folder structure for Ember puts controllers, routes and templates in three different directories. The Pods approach organizes the folders in correlation to the application routes and keeps all three files in the same folder for each view.

### Extensions, Mixins & Abstracts

This project has a massive usage of npm modules for ember, [ember mixins](http://emberjs.com/api/classes/Ember.Mixin.html) and abstracts.
This project has a massive usage of npm modules for Ember, [Ember mixins](http://emberjs.com/api/classes/Ember.Mixin.html) and abstracts.

[ember-simple-auth](https://ember-simple-auth.com/) is an example of an ember npm module used in the project to enable authentication and authorization.
[ember-simple-auth](https://ember-simple-auth.com/) is an example of an Ember npm module used in the project to enable authentication and authorization.

`app/mixins/number-format.js` is a mixin that, when augmenting a class, adds functions to it for working with number.
[app/mixins/number-format.js](/app/mixins/number-format.js) is a mixin that, when augmenting a class, adds functions to it for working with numbers.

`app/controllers/abstract-paged-controller.js` is an abstract that takes care of paging and displaying result.
[app/controllers/abstract-paged-controller.js](/app/controllers/abstract-paged-controller.js) is an abstract that takes care of paging and displaying results.
Using it is done like this:

```js
Expand All @@ -96,7 +94,7 @@ export default AbstractEditController.extend({

### Building the solution

Once you run `script/server` or `ember serve` the project is build and run. Afterwards you can change the models, controllers and templates and ember will automatically update those file.
Once you run `script/server` or `ember serve` the project is built and run. Afterwards you can change the models, controllers and templates and Ember will automatically update those files.

You can use `ember build` to actively build a project or `ember build --environment=production` to build the project for production.

Expand All @@ -106,35 +104,35 @@ You can use `ember build` to actively build a project or `ember build --environm

### Ember data

To make requests to the server the project utilizes [Ember data](http://emberjs.com/api/data/) and [REST Adapter](http://emberjs.com/api/data/classes/DS.RESTAdapter.html) to control requests between the client and the server.
To make requests to the server the project utilizes [Ember Data](http://emberjs.com/api/data/) and [REST Adapter](http://emberjs.com/api/data/classes/DS.RESTAdapter.html) to control requests between the client and the server.

### Adapters

Ember, by default uses http://jsonapi.org/ as a json convention. [CounchDB](http://couchdb.apache.org/) uses a different json convention. For that reason, an adapter (`app/adapters/application.js` which uses [ember-pouch](https://github.com/nolanlawson/ember-pouch)) was put between client to server communications to change server bound requests to CouchDB json format and client bound responses to [jsonapi](http://jsonapi.org) format.
Ember, by default uses [JSON API](http://jsonapi.org) as a JSON convention. [CouchDB](http://couchdb.apache.org/) uses a different JSON convention. For that reason, an adapter ([app/adapters/application.js](app/adapters/application.js) which uses [ember-pouch](https://github.com/nolanlawson/ember-pouch)) was put between client to server communications to change server bound requests to CouchDB JSON format and client bound responses to JSON API format.

### Components in use

[Ember components](http://emberjs.com/api/classes/Ember.Component.html) are reusable controls that you can integrate inside other pages\components.
[Ember components](http://emberjs.com/api/classes/Ember.Component.html) are reusable controls that you can integrate inside other pages/components.

### Using Local Cache

The database of **HospitalRun** uses [CouchDB](http://couchdb.apache.org/) to storage all of its data online.
The database of **HospitalRun** uses [CouchDB](http://couchdb.apache.org/) to store all of its data online.
In parallel, it uses the offline feature of [PouchDB](https://pouchdb.com/) to store an offline copy of the database which syncs with the online instance on a different thread whenever the application is online.

### Data Access Flow

There are 3 database elements in play:

1. Cloud based CouchDB
2. Pouch DB Online for online requests
3. Pouch DB Offline for synchronizing data on a separate thread
2. PouchDB Online for online requests
3. PouchDB Offline for synchronizing data on a separate thread

The application tries to access data via Pouch DB Online which tries to access data on the online Couch DB. If this request succeeds no more actions are required.
As a failover mechanism, all outbound requests are monitored by pouch DB service so they can be redirected to the local offline pouch DB instance.
The application tries to access data via PouchDB Online which tries to access data on the online CouchDB. If this request succeeds no more actions are required.
As a failover mechanism, all outbound requests are monitored by the PouchDB service so they can be redirected to the local offline PouchDB instance.

The main reason for keeping two services of pouch DB on the client side is that keeping the Pouch DB on the main thread, causes the UI to run slowly whenever a sync is running.
The main reason for keeping two services of PouchDB on the client side is that keeping the PouchDB on the main thread, causes the UI to run slowly whenever a sync is running.

### Conflicts

When there's a conflict in data, as long is the conflict occures between two different records or two different fields, the conflict resolution will be able to solve the conflict.
If the conflict is between two versions of the same field, the later record value will apply.
If the conflict is between two versions of the same field, the later record value will apply.