diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8c245b378..dd0b22b5bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,44 @@ +Use the following guidelines when contributing to this project. + + + +**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) + + + # Get involved There are many ways to get involved: @@ -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 @@ -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: @@ -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 +

+ + + Paragraph text. +

+``` + + +## 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. @@ -335,7 +287,7 @@ 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 @@ -343,7 +295,7 @@ 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 @@ -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 `