Skip to content

Commit

Permalink
chore: hoodie-server is the new hoodie
Browse files Browse the repository at this point in the history
BREAKING CHANGE:
`hoodie-server` has been merged into the `hoodie` main module. See
hoodiehq/discussion#94
  • Loading branch information
gr2m committed May 1, 2016
1 parent 45284b6 commit 0472d27
Show file tree
Hide file tree
Showing 15 changed files with 498 additions and 82 deletions.
166 changes: 166 additions & 0 deletions CODING_STYLE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
# Hoodie Coding Style Guidelines

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more guidelines on
contributing to Hoodie.

Hoodie uses the [Standard](https://github.com/feross/standard) JavaScript
coding style.

This file explains coding-style considerations that are beyond the syntax check
of *Standard*.

There are three sections:

- *General*: coding styles that are applicable to all JavaScript code.
- *Client*: coding styles that are only applicable to in-browser code.
- *Server*: coding styles that are only applicable in server code.

*Note: Client and Server coding styles can be contradicting, make sure to read
these carefully*.


## General

### File Structure

A typical JavaScript file looks like this (without the comments).
Sort all modules that you `require` alphabetically within their blocks.

```js
// If your module exports something, put it on top
module.exports = myMethod

// require Node.js core modules in the 1st block (separaeted by empty line).
// These are modules that come with Node.js and are not listed in package.json.
// See https://nodejs.org/api/ for a list of Node.js core modules
var EventEmitter = require('events').EventEmitter
var util = require('util')

// In the 2nd block, require all modules listed in package.json
var async = require('async')
var lodash = require('lodash')

// in the 3rd block, require all modules using relative paths
var helpers = require('./utils/helpers')
var otherMethod = require('./other-method')

function myMethod () {
// code here
}
```

### Avoid "this" and object-oriented coding styles.

Do this

```js
function MyApi (options) {
var state = {
foo: options.foo
}
return {
doSomething: doSomething.bind(null, state)
}
}

function doSomething (state) {
return state.foo ? 'foo!' : 'bar'
}
```

Instead of

```js
function MyApi (options) {
this.foo = options.foo
}

MyApi.prototype.doSomething = function () {
return this.foo ? 'foo!' : 'bar'
}
```

The [bind method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind)
allows for [partially applied functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind#Partially_applied_functions_%28currying%29), that way we can pass internal state between
different methods without exposing in the public API. At the same time we can
easily test the different methods in isolation by setting the internal state to
what ever context we want to test with.

### Folder Structure

In the root, have

- `package.json`
- `.gitignore` (should at least list node_modules)
- `README.md`
- `LICENSE` (Apache License Version 2.0)

In most cases you will have `index.js` file which is listed in `package.json`
as the `"main"` property.

If you want to split up logic into separate files, move them into a `lib/` folder.
Put reusable, state-less helper methods into `lib/utils/`

For tests, create a `test/` folder. If your module becomes a bit more complex,
split up the tests in `test/unit` and `test/integration/`. All files that contain
tests should end with `-test.js`.

### Misc

- Prefer [lodash](https://lodash.com) over [underscore](http://underscorejs.org "Underscore.js").


## Client

### Testing

Client code should be tested using [tape](https://www.npmjs.com/package/tape).
The reason we use tape is its support for [browserify](https://www.npmjs.com/package/browserify).

### Libraries with sub-modules that can be required individually, like lodash

For client-side JavaScript code, it is important to limit the amount of code
that is downloaded to the client to the code that is actually needed. The
[loadash](https://lodash.com) library is a collection of utilities that are
useful individually and in combination.

For example, if you want to use the `merge` function of lodash, require it like
this:

```javascript
var merge = require('lodash/merge')
```

If you want to use more than one function within one module, or if you want to
combine multiple functions for a single operation, require the full lodash
module:

```javascript
var _ = require('lodash')
```

If multiple modules use the same lodash function, [our frontend bundling
tool](http://browserify.org "Browserify") will do the right thing and only
include that code once.

## Server

### Testing

Server code should be tested using [tap](https://www.npmjs.com/package/tap).

### Libraries with sub-modules that can be required individually, like lodash

For server-side code, it is important to load the minimal amount of code into
memory.

On the server require the full library, e.g.

```javascript
var _ = require('lodash')

var c = _.merge(a, b)
```

That way, all of our server code will only ever load a single instance of
lodash into memory.
95 changes: 63 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,45 @@
![The Low-Profile Dog Hoodie Mascot](https://avatars1.githubusercontent.com/u/1888826?v=3&s=200)
# hoodie

# Welcome to Hoodie Server! 🎉
> A generic backend with a client API for Offline First applications
[![Build Status](https://travis-ci.org/hoodiehq/hoodie-server.svg?branch=next)](https://travis-ci.org/hoodiehq/hoodie-server)
[![Coverage Status](https://coveralls.io/repos/hoodiehq/hoodie-server/badge.svg?branch=next&service=github)](https://coveralls.io/github/hoodiehq/hoodie-server?branch=next)
[![Dependency Status](https://david-dm.org/hoodiehq/hoodie-server/next.svg)](https://david-dm.org/hoodiehq/hoodie-server/next)
[![devDependency Status](https://david-dm.org/hoodiehq/hoodie-server/next/dev-status.svg)](https://david-dm.org/hoodiehq/hoodie-server/next#info=dependencies)
[![Build Status](https://travis-ci.org/hoodiehq/hoodie.svg?branch=master)](https://travis-ci.org/hoodiehq/hoodie)
[![Dependency Status](https://david-dm.org/hoodiehq/hoodie.svg)](https://david-dm.org/hoodiehq/hoodie)
[![devDependency Status](https://david-dm.org/hoodiehq/hoodie/dev-status.svg)](https://david-dm.org/hoodiehq/hoodie#info=devDependencies)

<a href="http://hood.ie/animals/#low-profile-dog"><img src="https://avatars1.githubusercontent.com/u/1888826?v=3&s=200"
alt="The Low-Profile Dog Hoodie Mascot" title="The Low-Profile Dog Hoodie Mascot" align="right" /></a>

`@hoodie/server` is the core server component of Hoodie. Together with `@hoodie/client`, it forms the two parts that make up the Hoodie system.
Hoodie lets you build apps [without _thinking_ about the backend](http://nobackend.org/)
and makes sure that they work great [independent from connectivity](http://offlinefirst.org/).

`@hoodie/server` itself is responsible for only a few things:
This is Hoodie’s main repository. It starts a server and serves the client API.
Read more about [Hoodie’s core modules](#architecture).

- providing a normalized [config](lib/config.js) for itself and all core components/plugins
- providing an API to interact with [databases](lib/database.js) to components/plugins
- starting and configuring a [hapi server](lib/hapi.js) that also [serves static assets](lib/public.js) like hoodie-client and hoodie-admin-dashboard ([#493](https://github.com/hoodiehq/hoodie-server/issues/493))
A good place to start is our [Tracker App](https://github.com/hoodiehq/hoodie-app-tracker).
You can play around with Hoodie’s APIs in the browser console and see how it
works all together in its [simple HTML & JavaScript code](https://github.com/hoodiehq/hoodie-app-tracker/tree/master/public).

The rest is handled by components like [hoodie-account-server](https://github.com/hoodiehq/hoodie-account-server), or [hoodie-store-server](https://github.com/hoodiehq/hoodie-store-server).
If you have any questions come say hi in our [chat](http://hood.ie/chat/).

`@hoodie/server` isn’t meant to be used by itself and it is used by the `hoodie` module, which also inlcudes `@hoodie/client` to form Hoodie.
## Setup

You can use `@hoodie/server` on its own, if you want to work on it, help fix bugs or test new versions. And when you are writing your own components/plugins, you can use `@hoodie/server` for debugging.
`npm install --save hoodie`

## Usage

As noted before, this isn’t meant to be run standalone. But if you are helping out with development, building your own components/plugins, or just want to spelunk around, here’s how it works:
Add this to your `package.json`:

```json
"scripts": {
"start": "hoodie"
}
```
git clone git@github.com:hoodiehq/hoodie-server.git
cd hoodie-server
npm install @hoodie/start
npm install
./node_modules/.bin/hoodie-start
```

There are a few options to change the behaviour of `@hoodie/server`.
Now run `npm start` to start your Hoodie app.

## Usage

Run `npm start -- --help` to see all available CLI options.

Options can also be specified as environment variables (prefixed with `hoodie_`) or inside a `.hoodierc` file (json or ini).

option | default | description
------------- | ---------------------------------- | -------------
Expand All @@ -43,23 +48,49 @@ port | 8080 | Port-number to run the Hood
bindAddress | 127.0.0.1 | Address that Hoodie binds to
public | path.join(options.path, 'public') | path to static assets
inMemory | false | Whether to start the PouchDB Server in memory
dbUrl | PouchDB Server | If provided does not start PouchDB Server and uses external CouchDB. Has to contain credentials.
dbUrl | | If provided uses external CouchDB. Has to contain credentials.
data | path.join(options.path, '.hoodie') | Data path

If that doesn’t make much sense just yet, don’t worry about it.
Hoodie is using the [rc](https://www.npmjs.com/package/rc) module to retrieve
configuration from CLI arguments, environment variables and configuration files.

## Testing

The `@hoodie/server` test suite is run with `npm test`.
Local setup

```
git clone https://github.com/hoodiehq/hoodie.git
cd hoodie
npm install
```

The `hoodie` test suite is run with `npm test`.

You can [read more about testing Hoodie](test)

## Architecture

Hoodie is server built on top of [hapi](http://hapijs.com) with frontend APIs
for account and store related tasks.

The tests live in `test/unit` and `test/integration`. `test/unit` tests (or “unit tests”) are to test the behaviour of individual sub-modules within `@hoodie/server`, while `test/integration` tests (or “integration tests”) are used to test the behaviour of a fully running instance of `@hoodie/server`, e.g. the behaviour of its HTTP API.
It consists of three main components

If you are adding new features to `@hoodie/server` you should provide test cases for the new feature. Depending on the feature, it's either best to write unit tests or integration tests and sometimes even both. The more tests we have, the more confidently we can release future versions of `@hoodie/server`.
1. [**account**](https://github.com/hoodiehq/hoodie-account)
Hoodie’s account module. It exposes [JSON API](http://jsonapi.org/) routes,
a corresponding server API at `server.plugins.account.api`,
a client API and a generic account UI.

## Need help or want to help?
1. [**store**](https://github.com/hoodiehq/hoodie-store)
Hoodie’s store module. It exposes [CouchDB’s Document API](https://wiki.apache.org/couchdb/HTTP_Document_API),
a corresponding client and a generic store UI.

It’s best to join our [chat](http://hood.ie/chat/).
1. [**client**](https://github.com/hoodiehq/hoodie-client)
Hoodie’s front-end client for the browser. It integrates the following client modules:
1. [account-client](https://github.com/hoodiehq/hoodie-account-client)
2. [store-client](https://github.com/hoodiehq/hoodie-store-client)
3. [log-client](https://github.com/hoodiehq/hoodie-log-client)
4. [connection-status](https://github.com/hoodiehq/hoodie-connection-status)

## License

[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0)
[Apache 2.0](LICENSE)
100 changes: 95 additions & 5 deletions TRIAGING.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,98 @@
# Triaging new issues or Pull Requests on this repository
# Triage new issues/PRs on GitHub

![The Hoodie Mascot](https://avatars1.githubusercontent.com/u/1888826?v=3&s=200)
This document illustrates the steps the Hoodie community is taking to triage issues. The labels are used later on for [assigning work](#assigning-work). If you want to help by sorting issues please [leave a comment here](https://github.com/hoodiehq/discussion/issues/50) asking to join the triaging team.

We are sorry to make you click one more time, but we are collecting [all triaging information
in a single location](https://github.com/hoodiehq/hoodie/blob/master/TRIAGING.md). And here it is:
## Triaging Process

https://github.com/hoodiehq/hoodie/blob/master/TRIAGING.md
This process based on the idea of minimizing user pain
[from this blog post](http://www.lostgarden.com/2008/05/improving-bug-triage-with-user-pain.html).

1. Open the list of [non triaged issues](https://github.com/organizations/hoodiehq/dashboard/issues/repos?direction=desc&milestone=none&page=1&sort=created&state=open)
* Sort by submit date, with the newest issues first
* You don't have to do issues in order; feel free to pick and choose issues as you please.
* You can triage older issues as well
* Triage to your heart's content
1. Assign yourself: Pick an issue that is not assigned to anyone and assign it to you

1. Understandable? - verify if the description of the request is clear.
* If not, [close it][] according to the instructions below and go to the last step.
1. Duplicate?
* If you've seen this issue before [close it][], and go to the last step.
* Check if there are comments that link to a dupe. If so verify that this is indeed a dupe, [close it][], and go to the last step.
1. Bugs:
* Label `Type: Bug`
* Reproducible? - Steps to reproduce the bug are clear. If they are not, ask for a clarification. If there's no reply after a week, [close it][].
* Reproducible on master?

1. Non bugs:
* Label `Type: Feature`, `Type: Chore`, or `Type: Perf`
* Belongs in core? – Often new features should be implemented as a plugin rather than an addition to the core.
If this doesn't belong, [close it][], and go to the last step.
* Label `needs: breaking change` - if needed
* Label `needs: public api` - if the issue requires introduction of a new public API
1. Label `frequency: *` – How often does this issue come up? How many developers does this affect?
* low - obscure issue affecting a handful of developers
* moderate - impacts a common usage pattern
* high - impacts most or all Hoodie apps
1. Label `severity: *` - How bad is the issue?
* regression
* memory leak
* broken expected use - it's hard or impossible for a developer using Hoodie to accomplish something that Hoodie should be able to do
* confusing - unexpected or inconsistent behavior; hard-to-debug
* inconvenience - causes ugly/boilerplate code in apps
1. Label `starter` - These issues are good targets for PRs from the open source community. Apply to issues where the problem and solution are well defined in the comments, and it's not too complex.

1. Label `milestone: *` – Assign a milestone:
* Backlog - triaged fixes and features, should be the default choice
* x.y.z - e.g. 0.3.0


1. Unassign yourself from the issue

## Closing an Issue or PR

We're grateful to anyone who takes the time to submit an issue, even if we ultimately decide not to act on it.
Be kind and respectful as you close issues. Be sure to follow the [code of conduct][].

1. Always thank the person who submitted it.
1. If it's a duplicate, link to the older or more descriptive issue that supersedes the one you are closing.
1. Let them know if there's some way for them to follow-up.
* When the issue is unclear or reproducible, note that you'll reopen it if they can clarify or provide a better example. Mention [jsbin](https://jsbin.com) for examples. Watch your notifications and follow-up if they do provide clarification. :)
* If appropriate, suggest implementing a feature as a third-party module.

If in doubt, ask a core team member what to do.

**Example:**

> Thanks for submitting this issue!
> Unfortunately, we don't think this functionality belongs in core.
> The good news is that you could implement this as a plugin and publish it to npm with the `hoodie-plugin` keyword.

## Assigning Work

These criteria are then used to calculate a "user pain" score.
Work is assigned weekly to core team members starting with the highest pain, descending down to the lowest.

```
pain = severity × frequency
```

**severity:**

- regression (5)
- memory leak (4)
- broken expected use (3)
- confusing (2)
- inconvenience (1)

**frequency:**

- low (1)
- moderate (2)
- high (3)

**Note:** Regressions and memory leaks should almost always be set to `frequency: high`.

[close it]: #closing-an-issue-or-pr
[code of conduct]: http://hood.ie/code-of-conduct.html
Loading

0 comments on commit 0472d27

Please sign in to comment.