Skip to content

Feature/documentation improvements #1590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bajiat merged 9 commits into from
Sep 15, 2016
Merged

Feature/documentation improvements #1590

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
427d288
Move development installation instructions
brylie Sep 15, 2016
bddca85
Add table of contents; move 'contributing' to top
brylie Sep 15, 2016
781c9f2
Add table of contents
brylie Sep 15, 2016
a2cdd7f
Fix build status image
brylie Sep 15, 2016
d80462a
Change structure; add i18n section
brylie Sep 15, 2016
b933730
Update table of contents
brylie Sep 15, 2016
baf9bc8
Fix heading level; update TOC
brylie Sep 15, 2016
488f31b
Add indentation section
brylie Sep 15, 2016
abbd984
Update TOC
brylie Sep 15, 2016
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
209 changes: 103 additions & 106 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,44 @@
Use the following guidelines when contributing to this project.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Get involved](#get-involved)
- [Join the discussion](#join-the-discussion)
- [Submitting issues](#submitting-issues)
- [General details](#general-details)
- [Feature/enhancement requests](#featureenhancement-requests)
- [Feature/enhancement request example](#featureenhancement-request-example)
- [Bug reports / support requests](#bug-reports--support-requests)
- [Bug report/support request example](#bug-reportsupport-request-example)
- [Contributing code](#contributing-code)
- [Code quality](#code-quality)
- [Comments](#comments)
- [Example comment](#example-comment)
- [One task per line](#one-task-per-line)
- [Chaining example](#chaining-example)
- [Complex line example](#complex-line-example)
- [Variables](#variables)
- [Variable examples](#variable-examples)
- [Code standard(s) and Lint](#code-standards-and-lint)
- [Indentation](#indentation)
- [File structure](#file-structure)
- [File names](#file-names)
- [Collection/Schema structure](#collectionschema-structure)
- [Internationalization (i18n)](#internationalization-i18n)
- [i18n key structure](#i18n-key-structure)
- [Template text (HTML/Blaze)](#template-text-htmlblaze)
- [JavaScript text](#javascript-text)
- [Packages](#packages)
- [Forms](#forms)
- [Routing](#routing)
- [Schema](#schema)
- [Templating](#templating)
- [CSS](#css)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Get involved

There are many ways to get involved:
Expand All @@ -12,9 +53,6 @@ There are many ways to get involved:
* Join the [Apinf Community portal](https://community.apinf.io) - ask and answer questions, share ideas, etc.
* Hang out in the [Apinf IRC chatroom](https://webchat.freenode.net/?channels=apinf) ([#Apinf](irc://irc.freenode.net/apinf) on Freenode)

# Contributing
Use the following guidelines when contributing to this project.

# Submitting issues
There are a couple of common issue types in our tracker:
* Bug reports / support requests
Expand Down Expand Up @@ -90,106 +128,6 @@ When submitting a bug report or support request, include the following details,

**Note:** Some of the above details will be added during the discussion and testing process.

# Development installation with Docker

## Install Docker
Review the Docker installation instructions for your Operating System:
* [Mac](https://docs.docker.com/installation/mac/) ([Activates NFS on docker-machine](https://github.com/adlogix/docker-machine-nfs))
* [Linux](https://docs.docker.com/installation/ubuntulinux/)

Optionally [add your user to the `docker` group](https://docs.docker.com/engine/installation/linux/ubuntulinux/#create-a-docker-group).

## Install Docker Compose
You will also need to [install Docker Compose](https://docs.docker.com/compose/install/).
### Ubuntu
Install Docker Compose on Ubuntu Linux with the following command:

```
$ sudo apt install docker-compose
```

## Edit API Umbrella configuration

API Umbrella configuration should be stored in
* ```[project-root]/docker/api-umbrella/config/api-umbrella.yml```

You can create `api-umbrella.yml` based on the example:
* ```[project-root]/docker/api-umbrella/config/api-umbrella.yml.example```

## Prepare APInf image

1. Run application containers (in first time it will build image):
```
$ docker-compose up
```
2. Add `apinf.dev` and `api-umbrella.dev` hosts entry to `/etc/hosts` file so you can visit them from your browser.


### See Docker IP address (step only for Mac)
```
$ docker-machine ip
=> 127.0.0.1
```

### Set hosts

Then add the IP to your `/etc/hosts`:
```
127.0.0.1 apinf.dev api-umbrella.dev
```

Now you can work with your app from browser by visit http://apinf.dev:3000

## Create API Umbrella credentials

1. [Login to the API Umbrella web admin](http://api-umbrella.readthedocs.org/en/latest/getting-started.html#login-to-the-web-admin) https://api-umbrella.dev/admin/login
2. Signup to the APInf http://apinf.dev:3000/sign-up
3. Login to the APInf web admin http://apinf.dev:3000/sign-in
4. Fill API Umbrella settings http://apinf.dev:3000/settings :

* Host: https://api-umbrella.dev
* API Key: [Get from step](http://api-umbrella.readthedocs.org/en/latest/getting-started.html#signup-for-an-api-key).
* Auth Token: Get from [My account page](https://api-umbrella.dev/admin)
* Base URL: https://api-umbrella.dev
* Elasticsearch Host: http://api-umbrella.dev:14002

## Debugging containers with docker exec

This can be accomplished by grabbing the container ID with a docker ps, then passing that ID into the docker exec command:

```
$ docker ps
CONTAINER ID IMAGE
ce9de67fdcbe apinf/platform:latest
$ docker exec -it ce9de67fdcbe /bin/bash
root@ce9de67fdcbe:/#
```

Add alias to bash:
```
alias apinf_web='docker exec -it `docker ps | grep web | sed "s/ .*//"` /bin/bash'
```

## Building Docker Images

### Building Images

To build packages for the current APInf version:

```
$ docker build -t apinf/platform:INSERT_VERSION_HERE .
$ docker tag apinf/platform:INSERT_VERSION_HERE apinf/platform:latest
```

### Pushing to Docker Hub

To publish the new images to our [Docker Hub repository](https://hub.docker.com/r/apinf/platform/):

```
$ docker push apinf/platform:INSERT_VERSION_HERE
$ docker push apinf/platform:latest
```

# Contributing code
When contributing code, please follow the [Gitflow guidelines](http://danielkummer.github.io/git-flow-cheatsheet/). Specifically:

Expand Down Expand Up @@ -306,7 +244,21 @@ Configure your IDE to use eslint with the Airbnb styleguide.

Reference: Meteor Guide - Check Your Code with ESLint [Integrating with your editor](https://guide.meteor.com/code-style.html#eslint-editor)

# File structure
### Indentation
Indent all HTML(Blaze) and JavaScript code with two spaces for each level of nesting.

Also, nest most/all HTML child elements -- i.e. avoid having multiple inline elements.

```html
<p>
<!-- nesting is important for readability -->
<!-- e.g. when adding long internationalization keys -->
Paragraph text.
</p>
```


## File structure
This project is organized around a 'module' / 'component' architecture.

By 'module', we mean anything that has it's own database collection and one or more routes. Components are more closely related to the idea of [WebComponents](http://webcomponents.org/), which are intended to be reusable, hierarchical user interface elements. Modules are located in the project root, with components in the client sub-directory.
Expand Down Expand Up @@ -335,15 +287,15 @@ In general, our module structure follows this pattern:
* **server/**
* *methods.js*

## File names
### File names
Please use underscores in folder and file names, rather than hyphens or camel case. E.g.

```js
folder_name/file_name.css
folder_name/file_name.html
folder_name/file_name.js
```
# Collection/Schema structure
## Collection/Schema structure
After some trial and error, we have settled on the following pattern for defining collections and schemas:

```js
Expand Down Expand Up @@ -380,6 +332,51 @@ References:
- Meteor Guide: Code Style - [Collections](https://guide.meteor.com/code-style.html#collections)
- Meteor Guide: [Collections and Schemas](https://guide.meteor.com/collections.html#schemas)

## Internationalization (i18n)
To the extent possible, all user-facing text should be internationalized. To add internationalization support for texts, we use the following conventions.

### i18n key structure
Internationalization keys in our project use the following elements, separated by underscores
- `templateName` - the name of the template as it appears in either:
- the `<template name="templateName">`
- the `{{# AutoForm id="formName" }}`
- `pageElement` or `event` - indicate the page element or JS related event
- `additionalText` - additional text to distinguish this string from others (optional)


### Template text (HTML/Blaze)
Text in HTML/Blaze templates can be internationalized by adding an i18n tag:

```html
{{_ "templateName_pageElement_additionalText" }}
```

A specific example, found on a page element heading:

```html
<!-- note the element nesting, for readability -->
<h1 class="page-header">
{{_ "pageTemplate_header_text"}}
</h1>
```

### JavaScript text
When internationalization strings are used in JavaScript, use the following pattern:

1. fetch the ii18n string and store it in a descriptive variable
2. use the i18n variable in related code

For example, when showing an `sAlert` to the user:

```js
// Get a translation string
const message = TAPi18n._("templateName_event_translationString");

// Use the translation string
sAlert.warning(message);

```

# Packages
The project is built using the [Meteor.js framework](https://meteor.com). The following Meteor packages provide important functionality.

Expand Down
128 changes: 128 additions & 0 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,31 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Installation](#installation)
- [From Source Code](#from-source-code)
- [With Docker](#with-docker)
- [Configure APInf](#configure-apinf)
- [With Docker Compose](#with-docker-compose)
- [mail](#mail)
- [elasticsearch](#elasticsearch)
- [githubConfiguration](#githubconfiguration)
- [Development installation with Docker](#development-installation-with-docker)
- [Install Docker](#install-docker)
- [Install Docker Compose](#install-docker-compose)
- [Ubuntu](#ubuntu)
- [Edit API Umbrella configuration](#edit-api-umbrella-configuration)
- [Prepare APInf image](#prepare-apinf-image)
- [See Docker IP address (step only for Mac)](#see-docker-ip-address-step-only-for-mac)
- [Set hosts](#set-hosts)
- [Create API Umbrella credentials](#create-api-umbrella-credentials)
- [Debugging containers with docker exec](#debugging-containers-with-docker-exec)
- [Building Docker Images](#building-docker-images)
- [Building Images](#building-images)
- [Pushing to Docker Hub](#pushing-to-docker-hub)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Installation

## From Source Code
Expand Down Expand Up @@ -55,3 +83,103 @@ Elasticsearch takes a host value that contains the host and port of the API Umbr

## githubConfiguration
The Github configuration takes two values, a Client ID and Secret key. You can obtain these values by setting up a Github application from your Github user account.

# Development installation with Docker

## Install Docker
Review the Docker installation instructions for your Operating System:
* [Mac](https://docs.docker.com/installation/mac/) ([Activates NFS on docker-machine](https://github.com/adlogix/docker-machine-nfs))
* [Linux](https://docs.docker.com/installation/ubuntulinux/)

Optionally [add your user to the `docker` group](https://docs.docker.com/engine/installation/linux/ubuntulinux/#create-a-docker-group).

## Install Docker Compose
You will also need to [install Docker Compose](https://docs.docker.com/compose/install/).
### Ubuntu
Install Docker Compose on Ubuntu Linux with the following command:

```
$ sudo apt install docker-compose
```

## Edit API Umbrella configuration

API Umbrella configuration should be stored in
* ```[project-root]/docker/api-umbrella/config/api-umbrella.yml```

You can create `api-umbrella.yml` based on the example:
* ```[project-root]/docker/api-umbrella/config/api-umbrella.yml.example```

## Prepare APInf image

1. Run application containers (in first time it will build image):
```
$ docker-compose up
```
2. Add `apinf.dev` and `api-umbrella.dev` hosts entry to `/etc/hosts` file so you can visit them from your browser.


### See Docker IP address (step only for Mac)
```
$ docker-machine ip
=> 127.0.0.1
```

### Set hosts

Then add the IP to your `/etc/hosts`:
```
127.0.0.1 apinf.dev api-umbrella.dev
```

Now you can work with your app from browser by visit http://apinf.dev:3000

## Create API Umbrella credentials

1. [Login to the API Umbrella web admin](http://api-umbrella.readthedocs.org/en/latest/getting-started.html#login-to-the-web-admin) https://api-umbrella.dev/admin/login
2. Signup to the APInf http://apinf.dev:3000/sign-up
3. Login to the APInf web admin http://apinf.dev:3000/sign-in
4. Fill API Umbrella settings http://apinf.dev:3000/settings :

* Host: https://api-umbrella.dev
* API Key: [Get from step](http://api-umbrella.readthedocs.org/en/latest/getting-started.html#signup-for-an-api-key).
* Auth Token: Get from [My account page](https://api-umbrella.dev/admin)
* Base URL: https://api-umbrella.dev
* Elasticsearch Host: http://api-umbrella.dev:14002

## Debugging containers with docker exec

This can be accomplished by grabbing the container ID with a docker ps, then passing that ID into the docker exec command:

```
$ docker ps
CONTAINER ID IMAGE
ce9de67fdcbe apinf/platform:latest
$ docker exec -it ce9de67fdcbe /bin/bash
root@ce9de67fdcbe:/#
```

Add alias to bash:
```
alias apinf_web='docker exec -it `docker ps | grep web | sed "s/ .*//"` /bin/bash'
```

## Building Docker Images

### Building Images

To build packages for the current APInf version:

```
$ docker build -t apinf/platform:INSERT_VERSION_HERE .
$ docker tag apinf/platform:INSERT_VERSION_HERE apinf/platform:latest
```

### Pushing to Docker Hub

To publish the new images to our [Docker Hub repository](https://hub.docker.com/r/apinf/platform/):

```
$ docker push apinf/platform:INSERT_VERSION_HERE
$ docker push apinf/platform:latest
```
Loading