Skip to content

Latest commit

 

History

History
96 lines (70 loc) · 3.76 KB

CONTRIBUTING.md

File metadata and controls

96 lines (70 loc) · 3.76 KB
Raw

Contributing

Interested in contributing to RiveScript? Great!

First, check the general contributing guidelines for RiveScript and its primary implementations found at http://www.rivescript.com/contributing - in particular, understand the goals and scope of the RiveScript language and the style guide for the JavaScript implementation.

Quick Start

Fork, then clone the repo:

$ git clone git@github.com:your-username/rivescript-js.git

Make sure you have node and npm and set up the build dependencies:

# CLI dependencies if you don't have them already
$ npm install -g babel-cli webpack uglify-js nodeunit

# Install dev dependencies for rivescript-js
$ npm install

Make sure the unit tests still pass (npm run test), and add new unit tests if necessary for your change.

Push to your fork and submit a pull request.

At this point you're waiting on me. I'm usually pretty quick to comment on pull requests (within a few days) and I may suggest some changes or improvements or alternatives.

Some things that will increase the chance that your pull request is accepted:

Code Documentation Style

For this project I've adopted a JavaDoc-style documentation system in the source code. Look at existing function documentation for examples, but briefly:

  • Begin the comment block like: /**
  • Do NOT use a * as a prefix for each line.
  • The comment block should begin with the function definition prototype (use Java style data types to denote what each parameter should be)
  • Use a blank line between the function prototype and the description.
  • Use Markdown syntax - the documentation is generated as Markdown files and then rendered to HTML.
  • End the comment block with a */ sequence.
  • There should be no more comments touching the comment block (if you need a comment directly after the comment block, leave a blank line in between, or else that comment may end up becoming a part of the documentation!)

Examples:

  /**
  string processTags (string user, string msg, string reply, string[] stars,
                     string[] botstars, int step, scope)

  Process tags in a reply element.
  */
  processTags: (user, msg, reply, st, bst, step, scope) => {}
  ...

  /**
  int loadFile (string path || array path[, onSuccess[, onError]])

  Load a RiveScript document from a file. The path can either be a string that
  contains the path to a single file, or an array of paths to load multiple
  files. `onSuccess` is a function to be called when the file(s) have been
  successfully loaded. `onError` is for catching any errors, such as syntax
  errors.

  This loading method is asynchronous. You should define an `onSuccess`
  handler to be called when the file(s) have been successfully loaded.

  This method returns a "batch number" for this load attempt. The first call
  to this function will have the batch number of 0 and that will go up from
  there. This batch number is passed to your `onSuccess` handler as its only
  argument, in case you want to correlate it with your call to `loadFile()`.

  `onSuccess` receives: int batchNumber
  `onError` receives: string errorMessage[, int batchNumber]
  */
  loadFile: (path, onSuccess, onError) => {}

To compile the documentation, you'll need Python and the markdown module installed. If you can't do this, don't worry too much about it; the project maintainer will rebuild the documentation periodically. Quick start:

$ mkvirtualenv rivescript # (if you use virtualenvwrapper)
$ pip install markdown
$ python mkdoc.py