diff --git a/CODING_STYLE.md b/CODING_STYLE.md deleted file mode 100644 index 294f1e295..000000000 --- a/CODING_STYLE.md +++ /dev/null @@ -1,166 +0,0 @@ -# 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 `server/` folder. -Put reusable, state-less helper methods into `server/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. diff --git a/TRIAGING.md b/TRIAGING.md deleted file mode 100644 index 5a4eb1518..000000000 --- a/TRIAGING.md +++ /dev/null @@ -1,98 +0,0 @@ -# Triage new issues/PRs on GitHub - -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. - -## Triaging Process - -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/hoodiehq/hoodie/issues) - * 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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..0214ab1b8 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,68 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml epub latex latexpdf linkcheck + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " linkcheck to check all external links for integrity" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + diff --git a/docs/about/architecture.rst b/docs/about/architecture.rst index f02f5e2b5..52c83bc5c 100644 --- a/docs/about/architecture.rst +++ b/docs/about/architecture.rst @@ -26,7 +26,7 @@ We define simple Hapi plugins for `logging `__. Once everything is setup, the server is then started at the end of -`cli/start.js `__ +`cli/start.js `__ and the URL where hoodie is running is logged to the terminal. Modules diff --git a/docs/about/hoodie-concepts.rst b/docs/about/hoodie-concepts.rst index 325658b23..287457e71 100644 --- a/docs/about/hoodie-concepts.rst +++ b/docs/about/hoodie-concepts.rst @@ -97,7 +97,7 @@ First. **Offline First means: build your apps without the assumption of permanent connectivity**. Cache data and apps locally. Build interfaces -that accomodate the offline state elegantly. Design user interactions +that accommodate the offline state elegantly. Design user interactions that will not break if their train goes into a tunnel. Don't freak out your users with network error messages or frustrate them with inaccessible data. **Offline First apps are faster, more robust, more diff --git a/docs/api/index.rst b/docs/api/index.rst index 7e1ef38b0..5eb418d71 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -30,17 +30,17 @@ The Hoodie Client API This library, commonly called **Hoodie Client**, is what you'll be working with on the client side. It consists of: -- `The Hoodie Client API `__, which has +- `The Hoodie Client API `__, which has a couple of useful helpers -- `The account API `__, +- `The account API `__, which lets you do user authentication, such as signing users up, in and out -- `The store API `__, +- `The store API `__, which provides means to store and retrieve data for each individial user -- `The connectionStatus API `__, +- `The connectionStatus API `__, which provides helpers for connectivity. -- `The log API `__, which +- `The log API `__, which provides a nice API for logging all the things The Hoodie Server API diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..731e95d47 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,210 @@ +import os + +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Hoodie' +copyright = '2017 The Hoodie Firm' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# todo - Automatically read from git using git describe --tags +# +# The short X.Y version. +# version = sw_version.split('-')[0] +# The full version, including alpha/beta/rc tags. +# release = version + +suppress_warnings = ['image.nonlocal_uri'] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%Y-%m-%d' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +#html_theme = '' +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +# Custom Hoodie theming? +# html_style = 'css/hoodie.css' +else: + html_context = { + 'css_files': [ + 'https://media.readthedocs.org/css/sphinx_rtd_theme.css', + 'https://media.readthedocs.org/css/readthedocs-doc-embed.css', +# Custom Hoodie theming? +# '_static/css/hoodie.css', + ], + } + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = ['_themes'] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = 'low-profile-dog-1.png' + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = '_static/favicon.ico' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = 'hoodie_theme' + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%Y-%m-%d' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + 'index': ['sidebarlogo.html', 'sidebarusefullinks.html', 'searchbox.html'], + '**': ['sidebarlogo.html', 'relations.html', 'searchbox.html', 'localtoc.html', 'sidebarusefullinks.html'] +} +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +html_show_copyright = False + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'hoodiedoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '12pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('book', 'Hoodie.tex', 'Hoodie Documentation', + 'The Hoodie Firm', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = '_static/logo.png' + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +latex_show_urls = 'footnote' + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + +def setup(app): + from sphinx.util.texescape import tex_replacements + tex_replacements.append((u'↔', u'$\\leftrightarrow$')) diff --git a/docs/developers/CODING_STYLE.rst b/docs/developers/CODING_STYLE.rst new file mode 100644 index 000000000..7b2582060 --- /dev/null +++ b/docs/developers/CODING_STYLE.rst @@ -0,0 +1,184 @@ +Coding Style Guide +================== + +Please see `Contributing to Hoodie `__ for more guidelines on +contributing to Hoodie. + +Hoodie uses the `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. + +.. code:: 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 + +.. code:: 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 + +.. code:: js + + function MyApi (options) { + this.foo = options.foo + } + + MyApi.prototype.doSomething = function () { + return this.foo ? 'foo!' : 'bar' + } + +The `bind +method `__ +allows for `partially applied +functions `__, +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 +``server/`` folder. Put reusable, state-less helper methods into +``server/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 `__ over + `underscore `__. + +Client +------ + +Testing +~~~~~~~ + +Client code should be tested using +`tape `__. The reason we use tape is +its support for +`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 `__ 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: + +.. code:: 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: + +.. code:: javascript + + var _ = require('lodash') + +If multiple modules use the same lodash function, `our frontend bundling +tool `__ will do the right thing and only include +that code once. + +Server +------ + +Testing +~~~~~~~ + +Server code should be tested using +`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. + +.. code:: 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. diff --git a/docs/developers/CONTRIBUTING.rst b/docs/developers/CONTRIBUTING.rst new file mode 100644 index 000000000..3cee93c68 --- /dev/null +++ b/docs/developers/CONTRIBUTING.rst @@ -0,0 +1,277 @@ +Contributing to Hoodie +====================== + +Please take a moment to review this document in order to make the +contribution process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the +time of the developers managing and developing this open source project. +In return, they should reciprocate that respect in addressing your +issue, assessing changes, and helping you finalize your pull requests. + +As for everything else in the project, the contributions to Hoodie are +governed by our `Code of Conduct `__. + +Using the issue tracker +----------------------- + +First things first: **Do NOT report security vulnerabilities in public +issues!** Please disclose responsibly by letting `the Hoodie +team `__ know upfront. +We will assess the issue as soon as possible on a best-effort basis and +will give you an estimate for when we have a fix and release available +for an eventual public disclosure. + +The issue tracker is the preferred channel for `bug reports <#bugs>`__, +`features requests <#features>`__ and `submitting pull +requests <#pull-requests>`__, but please respect the following +restrictions: + +- Please **do not** use the issue tracker for personal support + requests. Use the `Hoodie Chat `__. + +- Please **do not** derail or troll issues. Keep the discussion on + topic and respect the opinions of others. + +Bug reports +----------- + +A bug is a *demonstrable problem* that is caused by the code in the +repository. Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the GitHub issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest ``master`` or ``next`` branch in the repository. + +3. **Isolate the problem** — ideally create a reduced test case. + +A good bug report shouldn't leave others needing to chase you up for +more information. Please try to be as detailed as possible in your +report. What is your environment? What steps will reproduce the issue? +What OS experiences the problem? What would you expect to be the +outcome? All these details will help people to fix any potential bugs. + +Example: + + Short and descriptive example bug report title + + A summary of the issue and the browser/OS environment in which it + occurs. If suitable, include the steps required to reproduce the + bug. + + 1. This is the first step + 2. This is the second step + 3. Further steps, etc. + + ```` - a link to the reduced test case + + Any other information you want to share that is relevant to the + issue being reported. This might include the lines of code that you + have identified as causing the bug, and potential solutions (and + your opinions on their merits). + +Feature requests +---------------- + +Feature requests are welcome. But take a moment to find out whether your +idea fits with the scope and aims of the project. It's up to *you* to +make a strong case to convince the project's developers of the merits of +this feature. Please provide as much detail and context as possible. + +Pull requests +------------- + +Good pull requests - patches, improvements, new features - are a +fantastic help. They should remain focused in scope and avoid containing +unrelated commits. + +**Please ask first** before embarking on any significant pull request +(e.g. implementing features, refactoring code), otherwise you risk +spending a lot of time working on something that the project's +developers might not want to merge into the project. + +For new Contributors +~~~~~~~~~~~~~~~~~~~~ + +If you never created a pull request before, welcome :tada: :smile: `Here +is a great +tutorial `__ +on how to send one :) + +1. `Fork `__ the project, clone + your fork, and configure the remotes: + +``bash # Clone your fork of the repo into the current directory git clone https://github.com// # Navigate to the newly cloned directory cd # Assign the original repo to a remote called "upstream" git remote add upstream https://github.com/hoodiehq/`` + +2. If you cloned a while ago, get the latest changes from upstream: + +``bash git checkout master git pull upstream master`` + +3. Create a new topic branch (off the main project development branch) + to contain your feature, change, or fix: + +``bash git checkout -b `` + +4. Make sure to update, or add to the tests when appropriate. Patches + and features will not be accepted without tests. Run ``npm test`` to + check that all tests pass after you've made changes. Look for a + ``Testing`` section in the project’s README for more information. + +5. If you added or changed a feature, make sure to document it + accordingly in the ``README.md`` file. + +6. Push your topic branch up to your fork: + +``bash git push origin `` + +8. `Open a Pull + Request `__ + with a clear title and description. + +For Members of the Hoodie Contributors Team +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Clone the repo and create a branch + +``bash git clone https://github.com/hoodiehq/ cd git checkout -b `` + +2. Make sure to update, or add to the tests when appropriate. Patches + and features will not be accepted without tests. Run ``npm test`` to + check that all tests pass after you've made changes. Look for a + ``Testing`` section in the project’s README for more information. + +3. If you added or changed a feature, make sure to document it + accordingly in the ``README.md`` file. + +4. Push your topic branch up to our repo + +``bash git push origin `` + +5. Open a Pull Request using your branch with a clear title and + description. + +Optionally, you can help us with these things. But don’t worry if they +are too complicated, we can help you out and teach you as we go :) + +1. Update your branch to the latest changes in the upstream master + branch. You can do that locally with + +``bash git pull --rebase upstream master`` + +Afterwards force push your changes to your remote feature branch. + +2. Once a pull request is good to go, you can tidy up your commit + messages using Git's `interactive + rebase `__. + Please follow our commit message conventions shown below, as they are + used by + `semantic-release `__ + to automatically determine the new version and release to npm. In a + nutshell: + +Commit Message Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Commit test files with ``test: ...`` or ``test(scope): ...`` prefix +- Commit bug fixes with ``fix: ...`` or ``fix(scope): ...`` prefix +- Commit breaking changes by adding ``BREAKING CHANGE:`` in the commit + body (not the subject line) +- Commit changes to ``package.json``, ``.gitignore`` and other meta + files with ``chore(filenamewithoutext): ...`` +- Commit changes to README files or comments with ``docs: ...`` +- Cody style changes with ``style: standard`` + +**IMPORTANT**: By submitting a patch, you agree to license your work +under the same license as that used by the project. + +Triagers +-------- + +There is a `defined process `__ to manage issues, because +this helps to speed up releases and minimizes user pain. Triaging is a +great way to contribute to Hoodie without having to write code. If you +are interested, please `leave a comment +here `__ asking to +join the triaging team. + +Maintainers +----------- + +If you have commit access, please follow this process for merging +patches and cutting new releases. + +Reviewing changes +~~~~~~~~~~~~~~~~~ + +1. Check that a change is within the scope and philosophy of the + component. +2. Check that a change has any necessary tests. +3. Check that a change has any necessary documentation. +4. If there is anything you don’t like, leave a comment below the + respective lines and submit a "Request changes" review. Repeat until + everything has been addressed. +5. If you are not sure about something, mention ``@hoodie/maintainers`` + or specific people for help in a comment. +6. If there is only a tiny change left before you can merge it and you + think it’s best to fix it yourself, you can directly commit to the + author’s fork. Leave a comment about it so the author and others + will know. +7. Once everything looks good, add an "Approve" review. Don’t forget to + say something nice 👏🐶💖✨ +8. If the commit messages follow `our + conventions <@commit-message-conventions>`__ + +9. If there is a breaking change, make sure that ``BREAKING CHANGE:`` + with *exactly* that spelling (incl. the ":") is in body of the + according commit message. This is *very important*, better look + twice :) +10. Make sure there are ``fix: ...`` or ``feat: ...`` commits depending + on whether a bug was fixed or a feature was added. **Gotcha:** look + for spaces before the prefixes of ``fix:`` and ``feat:``, these get + ignored by semantic-release. +11. Use the "Rebase and merge" button to merge the pull request. +12. Done! You are awesome! Thanks so much for your help 🤗 + +13. If the commit messages *do not* follow our conventions + +14. Use the "squash and merge" button to clean up the commits and merge + at the same time: ✨🎩 +15. Is there a breaking change? Describe it in the commit body. Start + with *exactly* ``BREAKING CHANGE:`` followed by an empty line. For + the commit subject: +16. Was a new feature added? Use ``feat: ...`` prefix in the commit + subject +17. Was a bug fixed? Use ``fix: ...`` in the commit subject + +Sometimes there might be a good reason to merge changes locally. The +process looks like this: + +Reviewing and merging changes locally +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + git checkout master # or the main branch configured on github + git pull # get latest changes + git checkout feature-branch # replace name with your branch + git rebase master + git checkout master + git merge feature-branch # replace name with your branch + git push + +When merging PRs from forked repositories, we recommend you install the +`hub `__ command line tools. + +This allows you to do: + +:: + + hub checkout link-to-pull-request + +meaning that you will automatically check out the branch for the pull +request, without needing any other steps like setting git upstreams! +:sparkles: diff --git a/docs/developers/CONTRIBUTING_DOCS.rst b/docs/developers/CONTRIBUTING_DOCS.rst new file mode 100644 index 000000000..b4d98304d --- /dev/null +++ b/docs/developers/CONTRIBUTING_DOCS.rst @@ -0,0 +1,39 @@ +Contributing to Documentation +========================================== + +This guide describes how to make changes to Hoodie documentation. + +Make small changes +-------------------- + +We love small contributions, if you spot small errors or additions please feel free to request a change. Every page on `Hoodie documentation `_ has an "Edit on GitHub" button on the top right corner, please use this to make changes. + +Hoodie documentation uses the `reStructuredText `_ format. This may be unfamiliar but provides advanced features which are useful for complex documentation. + +The Github editor is very basic, if you need more editing tools try copying and pasting into this online `editor `_. You can then click 'commit' and create a 'pull request' on Github. The pull request will be automatically tested for grammar, style and common misspellings. Your changes will then be reviewed by a Hoodie Admin, who may suggest changes. Please read the `Documentation Style Guide `__ for advice on writing and more info on testing. + +Make big changes +------------------ + +For big changes, follow the `Contributing to Hoodie guidelines for new contributors `__. This allows you to build and test the documentation locally. For example, adding, moving or updating several documents. The index.rst file in the docs/ folder controls the order in which the documents are displayed on the docs webpages. Remember to update the index file if you have removed, added or want to reorder the documents. + +To build the docs locally, you will need to install `python 2.7+ `_ + +Then install two pip packages: `Sphinx `_ and `sphinx_rtd_theme `_. + + ``sudo pip sphinx`` + + ``sudo pip sphinx_rtd_theme`` + +Change directory to ..hoodie/docs/ + + ``make html`` + +After building, your updated documents are in the docs/_build/html subdirectory. Click on any .html document, this will open your web browser and the documents will be viewable. + +`Get in touch `_ if you have any questions or want to contribute to Hoodie documentation. + + + + + diff --git a/docs/developers/DOCS_STYLE.rst b/docs/developers/DOCS_STYLE.rst new file mode 100644 index 000000000..e17371e94 --- /dev/null +++ b/docs/developers/DOCS_STYLE.rst @@ -0,0 +1,91 @@ +Documentation Style Guide +========================= + +This guide provides style advice for how to write documentation. Please take the time to read this before contributing a large change or update to documentation. + +Style helps you and your reader +------------------------------- +Word choice and writing style are a personal choice and we understand documentation can be difficult to write. These recommendations have been designed to help you write clear and beautiful documents. + +Testing +------- +The `contributing to docs guide `_ describes the process to follow when updating documentation. This process includes automatic testing. Testing provides you peace of mind that your contribution won't contain typos, broken links or other style whoopsies. Testing is not used to criticise your writing, we really love and appreciate any contributions. Please be patience through the testing and review process. Together we can keep Hoodie documentation awesome! + +Style guidance +-------------- + +Please see the helpful `guide `_ provided by OpenStack documentation. This guide will further explain these key style tips: + +- Use standard English +- Write in active voice +- Use the present simple tense +- Write in second person +- Use appropriate mood +- Keep sentences short +- Avoid ambiguous titles +- Be clear and concise +- Write objectively +- Describe the most common use case first +- Do not humanize inanimate objects +- Write positively +- Avoid prepositions at the end of sentences +- Do no overuse this, that, these, and it +- Do not split infinitives +- Avoid personification +- Eliminate needless politeness +- Use consistent terminology +- Use spelling and grammar checking tools + + +Automatic testing +------------------ + +The current tests we run on pull requests using Travis Continuous Integration (CI) service: + ++----------------------------------------------------------------+------------+-----------+------------+ +| Style guide | Tested | Test type | Package | ++================================================================+============+===========+============+ +| Keep sentences short, concise and readable | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Write in the `active`_ voice | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Avoid "Lexical illusion's" – cases where a word is repeated | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Check for 'So' at the beginning of sentences | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Avoid adverbs that can weaken meaning: really, very, | | | | +| extremely, etc | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Use the most simple expressions | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Avoid using "weasel words": quite, several, mostly etc | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Leave no space between a sentence and its | | | | +| ending punctuation | ✔ | Warning |`rousseau`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Spell checker - we test for common misspelling but please | | | | +| check technical words | ✔ | Error |`common`_ | ++----------------------------------------------------------------+------------+-----------+------------+ +| Broken or dead links (excluding redirects) | ✔ | Error |`awesome`_ | ++----------------------------------------------------------------+------------+-----------+------------+ + + .. _active: https://docs.openstack.org/contributor-guide/writing-style/general-writing-guidelines.html#write-in-active-voice + .. _rousseau: https://github.com/GitbookIO/rousseau + .. _common: https://github.com/io-monad/textlint-rule-common-misspellings + .. _awesome: https://github.com/dkhamsing/awesome_bot + +- Remember, follow the `Code of Conduct `__ + +Bonus style points +~~~~~~~~~~~~~~~~~~ +- Be fun and friendly as long as it does not distract or confuse the reader +- Include videos or gifs to demostrated a feature +- You can use Humour but remember the reader is looking for an *answer* not a comedy sketch +- Cultural references and puns don't always translate - keep jokes light +- Remember English is not the first language for many readers - keep language simple where possible + +.. _second: https://docs.openstack.org/contributor-guide/writing-style/general-writing-guidelines.html#write-in-second-person + +Further reading +--------------- +This guide is influenced by the `Open Stack `_ style guide. diff --git a/docs/developers/TRIAGING.rst b/docs/developers/TRIAGING.rst new file mode 100644 index 000000000..2d70ed236 --- /dev/null +++ b/docs/developers/TRIAGING.rst @@ -0,0 +1,144 @@ +Triage new issues/PRs on GitHub +=============================== + +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 `__ asking to +join the triaging team. + +Triaging Process +---------------- + +This process based on the idea of minimizing user pain `from this blog +post `__. + +1. Open the list of `non triaged + issues `__ + + - 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 + +2. Assign yourself: Pick an issue that is not assigned to anyone and + assign it to you + +3. Understandable? - verify if the description of the request is clear. + + - If not, `close it <#closing-an-issue-or-pr>`__ according to the + instructions below and go to the last step. + +4. Duplicate? + + - If you've seen this issue before `close + it <#closing-an-issue-or-pr>`__, 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 <#closing-an-issue-or-pr>`__, and go to the last step. + +5. 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 <#closing-an-issue-or-pr>`__. + - Reproducible on master? + +6. 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 <#closing-an-issue-or-pr>`__, 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 + +7. 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 + +8. 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 + +9. 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. + +10. 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. +2. If it's a duplicate, link to the older or more descriptive issue that + supersedes the one you are closing. +3. 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 `__ 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``. diff --git a/docs/guides/configuration.rst b/docs/guides/configuration.rst index ec498d14a..b6db782bb 100644 --- a/docs/guides/configuration.rst +++ b/docs/guides/configuration.rst @@ -33,6 +33,7 @@ Here is a list of all available options +-----------------+--------------------------+--------------------------+--------------------------+---------------------------------------------------------------------------------------------------------------------+ | adminPassword | - | ``--adminPassword`` | ``hoodie_adminPassword`` | Password to login to Admin Dashboard. Login is not possible unless set | +-----------------+--------------------------+--------------------------+--------------------------+---------------------------------------------------------------------------------------------------------------------+ + Defaults -------- @@ -61,7 +62,7 @@ default values ~~~~~~~~~ The ``.hoodierc`` can be used to set configuration when running your Hoodie -backend in that folder. It should not be comitted to your repository. +backend in that folder. It should not be committed to your repository. The content can be in JSON or INI format. See the `rc package on npm `__ for more information diff --git a/docs/guides/deployment.rst b/docs/guides/deployment.rst index c72e49052..aecce8f49 100644 --- a/docs/guides/deployment.rst +++ b/docs/guides/deployment.rst @@ -4,9 +4,10 @@ Deployment One line deploy ~~~~~~~~~~~~~~~ -After you’ve built your Hoodie app you probably want to put it online. You can choose to deploy your app as read-only or deploy the backend couchdb database as well. This `video`_ and the text below descibes how to deploy your app using one line of code. Alternatively, you can deploy your app using Docker, please refer to the Docker section. +After you’ve built your Hoodie app you probably want to put it online. You can choose to deploy your app as read-only or deploy the backend couchdb database as well. This `video`_ and the text below describes how to deploy your app using one line of code. Alternatively, you can deploy your app using Docker, please refer to the Docker section. .. _video: https://youtu.be/29Uclxq_1Vw + Deploying to Now ~~~~~~~~~~~~~~~~ .. _command line tool: https://github.com/zeit/now-cli @@ -17,7 +18,7 @@ Deploying to Now $ now hoodiehq/hoodie-app-tracker --npm -e NODE_ENV=production -e hoodie_inMemory=true -To decribe this further: +To describe this further: - :code:`hoodiehq/hoodie-app-tracker` is the GitHub repository slug. @@ -34,6 +35,7 @@ Alternatively, add this script to your package.json and you are good to go: "now-start": "hoodie --inMemory", .. _Now: https://zeit.co/now + Store Data With Cloudant ~~~~~~~~~~~~~~~~~~~~~~~~ .. _Cloudant: https://cloudant.com/_ diff --git a/docs/index.rst b/docs/index.rst index 256b6e553..0cbaa64bc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,6 +21,16 @@ Hoodie Documentation api/index +.. toctree:: + :maxdepth: 1 + :caption: Developers + + developers/CONTRIBUTING + developers/CODING_STYLE + developers/TRIAGING + developers/CONTRIBUTING_DOCS + developers/DOCS_STYLE + .. toctree:: :maxdepth: 1 :caption: About